PR #28260: Fix/fallback headers sdk completion

• Repository: BerriAI/litellm
• Author: V-3604
• State: open | merged: False
• Link: https://github.com/BerriAI/litellm/pull/28260

Description (problem / solution / changelog)

Relevant issues

Fixes #28241

Linear ticket

N/A

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

<!-- Include screenshots, screen recordings, or log output demonstrating that your changes work as expected. For bug fixes: show reproduction before the fix and passing behavior after. For new features: show the feature working end-to-end. For UI changes: include before/after screenshots. -->

Before this fix, SDK-level fallbacks could return the fallback model from LiteLLM, but the proxy response-model override could not detect that a fallback happened because x-litellm-attempted-fallbacks was missing or prefixed as a provider header. The override then stamped the originally requested model back onto the response.

<img width="2066" height="1275" alt="ss2" src="https://github.com/user-attachments/assets/b040f9d5-b4de-4525-ba47-f83170e2b8b8" />

After this fix:

<img width="2554" height="864" alt="Untitled" src="https://github.com/user-attachments/assets/940bee45-784d-4297-873a-27d2a554e540" />

Type

<!-- Select the type of Pull Request --> <!-- Keep only the necessary ones -->

🐛 Bug Fix

Changes

This fixes SDK-level fallbacks so the response keeps reporting the actual fallback model that handled the request.

When a fallback succeeds, async_completion_with_fallbacks now adds the same x-litellm-attempted-fallbacks marker that the router fallback path already sets. This lets downstream code detect that the primary model failed and a fallback model was used.

process_response_headers now keeps LiteLLM-owned x-litellm-* headers unchanged instead of treating them like upstream provider headers. Provider headers are still prefixed with llm_provider-*, but LiteLLM internal markers remain available under their original names.

Added regression tests for the fallback header, the primary-success case, and preservation of x-litellm-* response headers.

Changed files

• litellm/litellm_core_utils/core_helpers.py (modified, +18/-1)
• litellm/litellm_core_utils/fallback_utils.py (modified, +8/-2)
• litellm/litellm_core_utils/llm_response_utils/response_metadata.py (modified, +2/-1)
• tests/test_litellm/litellm_core_utils/test_fallback_utils.py (added, +110/-0)