fix(backends/litellm): keep the upstream 4xx status on send_message errors (#3944)

## Description

Fixes #3943.

The LiteLLM backend turned any upstream error it did not recognise by
message text into HTTP 500, so an upstream 400 reached the client as a
500 and its retry-on-400 fallback never ran. The Anthropic and OpenAI
error paths now use the exception's own 4xx `status_code` (400, 401,
403, 404, 413, 422, 429) with a matching error type, and keep the old
message matching otherwise.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Map 4xx status; add tests.

## Testing

- [x] Unit tests pass (`pytest`) (new file only)
- [x] Linting passes (`ruff check .`) (changed files)
- [ ] Type checking passes (`mypy headroom`) (not run)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
# Paste relevant command output or artifact links here
tests/test_litellm_transport_errors.py: 22 passed, 4 skipped
ruff check (changed files): All checks passed!
```

## Real Behavior Proof

- Environment: local venv, mocked upstream
- Exact command / steps: the pytest run above
- Observed result: BadRequestError gives 400, was 500
- Not tested: real Bedrock

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: upstream 4xx keep their status
- Kill switch / disable path: none
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [ ] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

N/A

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3944"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Younes Beriane
2026-10-04 13:55:42 -07:00
committed by GitHub
co-authored by Claude Sonnet 5.5 JD Davis
parent d0e9c4ca48
commit e0e41cd2f5
2 changed files with 203 additions and 2 deletions
+46 -2
View File
@@ -557,6 +557,44 @@ def get_provider_config(provider: str) -> ProviderConfig:
)
_ANTHROPIC_ERROR_TYPES = {
400: "invalid_request_error",
401: "authentication_error",
403: "permission_error",
404: "not_found_error",
413: "request_too_large",
422: "invalid_request_error",
429: "rate_limit_error",
}
_OPENAI_ERROR_TYPES = {
400: "invalid_request_error",
401: "invalid_api_key",
403: "permission_error",
404: "model_not_found",
413: "invalid_request_error",
422: "invalid_request_error",
429: "rate_limit_exceeded",
}
def _upstream_client_error(exc: Exception, error_types: dict[int, str]) -> tuple[int, str] | None:
"""Map a LiteLLM exception's own 4xx ``status_code`` to ``(status, error type)``.
A 4xx status outside ``error_types`` keeps its status with the generic
``invalid_request_error`` type. Returns None when the exception carries no
4xx status, so the caller falls back to matching on the message.
"""
status = getattr(exc, "status_code", None)
if not isinstance(status, int) or isinstance(status, bool):
return None
if status in error_types:
return status, error_types[status]
if 400 <= status <= 499:
return status, "invalid_request_error"
return None
def _anthropic_usage_from_litellm(litellm_usage: Any) -> dict[str, Any]:
"""Map LiteLLM usage to Anthropic-shape usage, surfacing cache tokens.
@@ -1291,7 +1329,10 @@ class LiteLLMBackend(Backend):
status_code = 500
error_str = str(e).lower()
if "authentication" in error_str or "credentials" in error_str:
upstream = _upstream_client_error(e, _ANTHROPIC_ERROR_TYPES)
if upstream is not None:
status_code, error_type = upstream
elif "authentication" in error_str or "credentials" in error_str:
error_type = "authentication_error"
status_code = 401
elif "rate" in error_str or "limit" in error_str:
@@ -1925,7 +1966,10 @@ class LiteLLMBackend(Backend):
status_code = 500
error_str = str(e).lower()
if "authentication" in error_str or "credentials" in error_str:
upstream = _upstream_client_error(e, _OPENAI_ERROR_TYPES)
if upstream is not None:
status_code, error_type = upstream
elif "authentication" in error_str or "credentials" in error_str:
error_type = "invalid_api_key"
status_code = 401
elif "rate" in error_str or "limit" in error_str:
+157
View File
@@ -217,3 +217,160 @@ def test_bedrock_stream_names_transport_error_without_message() -> None:
assert response.status_code == 200
assert _TIMEOUT in response.text
assert '"code": "upstream_timeout"' in response.text
def _upstream_error(status_code: int, message: str) -> Exception:
"""A LiteLLM-style exception: carries the upstream HTTP status as an attribute."""
import litellm
classes = {
400: litellm.BadRequestError,
401: litellm.AuthenticationError,
403: litellm.PermissionDeniedError,
404: litellm.NotFoundError,
422: litellm.UnprocessableEntityError,
429: litellm.RateLimitError,
500: litellm.InternalServerError,
}
if status_code not in classes:
# Unmapped 4xx: litellm bakes the status into each class, so use a bare
# exception carrying only the ``status_code`` attribute.
err = Exception(message)
err.status_code = status_code # type: ignore[attr-defined]
return err
response = httpx.Response(status_code, request=httpx.Request("POST", "https://upstream.test"))
return classes[status_code](
message=message, model="bedrock/claude", llm_provider="bedrock", response=response
)
_BAD_THINKING = (
"BedrockException - thinking.adaptive.display: Input should be 'summarized', 'omitted'"
)
@pytest.mark.asyncio
@pytest.mark.parametrize(
("status", "error_type"),
[
(400, "invalid_request_error"),
(403, "permission_error"),
(422, "invalid_request_error"),
(401, "authentication_error"),
(404, "not_found_error"),
(429, "rate_limit_error"),
(402, "invalid_request_error"),
(408, "invalid_request_error"),
(409, "invalid_request_error"),
(500, "api_error"),
],
)
async def test_send_message_keeps_upstream_litellm_status(status: int, error_type: str) -> None:
with (
patch(
"headroom.backends.litellm.acompletion",
new_callable=AsyncMock,
side_effect=_upstream_error(status, _BAD_THINKING),
),
patch("headroom.backends.litellm._fetch_bedrock_inference_profiles", return_value={}),
):
backend = LiteLLMBackend(provider="bedrock", region="us-east-1")
result = await backend.send_message(_BODY, {})
assert result.status_code == status
assert result.body["error"]["type"] == error_type
@pytest.mark.asyncio
@pytest.mark.parametrize(
("status", "error_type"),
[
(400, "invalid_request_error"),
(403, "permission_error"),
(422, "invalid_request_error"),
(401, "invalid_api_key"),
(404, "model_not_found"),
(429, "rate_limit_exceeded"),
(402, "invalid_request_error"),
(408, "invalid_request_error"),
(409, "invalid_request_error"),
(500, "api_error"),
],
)
async def test_send_openai_message_keeps_upstream_litellm_status(
status: int, error_type: str
) -> None:
with (
patch(
"headroom.backends.litellm.acompletion",
new_callable=AsyncMock,
side_effect=_upstream_error(status, _BAD_THINKING),
),
patch("headroom.backends.litellm._fetch_bedrock_inference_profiles", return_value={}),
):
backend = LiteLLMBackend(provider="bedrock", region="us-east-1")
result = await backend.send_openai_message(_BODY, {})
assert result.status_code == status
assert result.body["error"]["type"] == error_type
@pytest.mark.asyncio
async def test_send_message_substring_fallback_without_status_attribute() -> None:
with (
patch(
"headroom.backends.litellm.acompletion",
new_callable=AsyncMock,
side_effect=RuntimeError("Authentication failed: bad credentials"),
),
patch("headroom.backends.litellm._fetch_bedrock_inference_profiles", return_value={}),
):
backend = LiteLLMBackend(provider="bedrock", region="us-east-1")
result = await backend.send_message(_BODY, {})
assert result.status_code == 401
assert result.body["error"]["type"] == "authentication_error"
class _StatusError(Exception):
def __init__(self, status_code: object) -> None:
super().__init__("payload too large")
self.status_code = status_code
@pytest.mark.asyncio
@pytest.mark.parametrize(
("method", "error_type"),
[("send_message", "request_too_large"), ("send_openai_message", "invalid_request_error")],
)
async def test_413_status_attribute_is_kept(method: str, error_type: str) -> None:
with (
patch(
"headroom.backends.litellm.acompletion",
new_callable=AsyncMock,
side_effect=_StatusError(413),
),
patch("headroom.backends.litellm._fetch_bedrock_inference_profiles", return_value={}),
):
backend = LiteLLMBackend(provider="bedrock", region="us-east-1")
result = await getattr(backend, method)(_BODY, {})
assert result.status_code == 413
assert result.body["error"]["type"] == error_type
@pytest.mark.asyncio
async def test_non_int_status_attribute_falls_back_to_substring() -> None:
with (
patch(
"headroom.backends.litellm.acompletion",
new_callable=AsyncMock,
side_effect=_StatusError("429"),
),
patch("headroom.backends.litellm._fetch_bedrock_inference_profiles", return_value={}),
):
backend = LiteLLMBackend(provider="bedrock", region="us-east-1")
result = await backend.send_message(_BODY, {})
assert result.status_code == 500
assert result.body["error"]["type"] == "api_error"