Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Improve provider error diagnostics

Alishahryar1327b393b05fe
diff --git a/core/anthropic/errors.py b/core/anthropic/errors.py
index afe093d6..9b776941 100644
--- a/core/anthropic/errors.py
+++ b/core/anthropic/errors.py
@@ -21,31 +21,90 @@ def get_user_facing_error_message(
return "Provider request timed out."
if isinstance(e, httpx.ConnectTimeout):
return "Could not connect to provider."
+ if isinstance(e, httpx.TimeoutException):
+ if read_timeout_s is not None:
+ return f"Provider request timed out after {read_timeout_s:g}s."
+ return "Provider request timed out."
+ if isinstance(e, httpx.ConnectError):
+ return "Could not connect to provider."
+ if isinstance(e, httpx.RemoteProtocolError):
+ return "Provider connection was interrupted."
+ if isinstance(e, httpx.ProtocolError):
+ return "Provider stream failed."
if isinstance(e, TimeoutError):
if read_timeout_s is not None:
return f"Provider request timed out after {read_timeout_s:g}s."
return "Request timed out."
+ if isinstance(e, openai.APITimeoutError):
+ if read_timeout_s is not None:
+ return f"Provider request timed out after {read_timeout_s:g}s."
+ return "Provider request timed out."
+ if isinstance(e, openai.APIConnectionError):
+ return "Could not connect to provider."
if isinstance(e, openai.RateLimitError):
return "Provider rate limit reached. Please retry shortly."
if isinstance(e, openai.AuthenticationError):
return "Provider authentication failed. Check API key."
+ if isinstance(e, openai.PermissionDeniedError):
+ return (
+ "Provider authorization failed (HTTP 403). Check API key, account "
+ "permissions, or model access."
+ )
+ if isinstance(e, openai.NotFoundError):
+ return (
+ "Provider endpoint or model was not found (HTTP 404). Check the "
+ "configured provider model."
+ )
if isinstance(e, openai.BadRequestError):
return "Invalid request sent to provider."
+ if isinstance(e, openai.ConflictError):
+ return "Provider rejected the request due to a conflict (HTTP 409)."
+ if isinstance(e, openai.UnprocessableEntityError):
+ return "Provider rejected unsupported request content (HTTP 422)."
name = type(e).__name__
- status_code = getattr(e, "status_code", None)
+ status_code = _status_code_from_exception(e)
+ provider_message = _mapped_provider_error_message(e)
+ if provider_message is not None:
+ return provider_message
if name == "RateLimitError":
return "Provider rate limit reached. Please retry shortly."
if name == "AuthenticationError":
return "Provider authentication failed. Check API key."
+ if name == "PermissionDeniedError" or status_code == 403:
+ return (
+ "Provider authorization failed (HTTP 403). Check API key, account "
+ "permissions, or model access."
+ )
if name == "InvalidRequestError":
return "Invalid request sent to provider."
if name == "OverloadedError":
return "Provider is currently overloaded. Please retry."
+ if status_code == 400:
+ return "Invalid request sent to provider."
+ if status_code == 401:
+ return "Provider authentication failed. Check API key."
+ if status_code == 408:
+ if read_timeout_s is not None:
+ return f"Provider request timed out after {read_timeout_s:g}s."
+ return "Provider request timed out."
+ if status_code == 409:
+ return "Provider rejected the request due to a conflict (HTTP 409)."
+ if status_code == 404:
+ return (
+ "Provider endpoint or model was not found (HTTP 404). Check the "
+ "configured provider model."
+ )
+ if status_code == 422:
+ return "Provider rejected unsupported request content (HTTP 422)."
+ if status_code == 429:
+ return "Provider rate limit reached. Please retry shortly."
+ if status_code in (502, 503, 504):
+ return "Provider is temporarily unavailable. Please retry."
+ if isinstance(status_code, int):
+ return f"Provider API request failed (HTTP {status_code})."
if name == "APIError":
- if status_code in (502, 503, 504):
- return "Provider is temporarily unavailable. Please retry."
return "Provider API request failed."
if name.endswith("ProviderError") or name == "ProviderError":
return "Provider request failed."
@@ -57,6 +116,31 @@ def get_user_facing_error_message(
return "Provider request failed unexpectedly."
+def _mapped_provider_error_message(e: Exception) -> str | None:
+ """Return this app's already-sanitized provider message when meaningful."""
+ if type(e).__module__ != "providers.exceptions":
+ return None
+ provider_message = getattr(e, "message", "")
+ if not isinstance(provider_message, str):
+ return None
+ message = provider_message.strip()
+ if not message or message == "_":
+ return None
+ return message
+
+
+def _status_code_from_exception(e: Exception) -> int | None:
+ """Extract an HTTP status code from SDK, provider, or httpx exceptions."""
+ status_code = getattr(e, "status_code", None)
+ if isinstance(status_code, int):
+ return status_code
+ response = getattr(e, "response", None)
+ response_status = getattr(response, "status_code", None)
+ if isinstance(response_status, int):
+ return response_status
+ return None
+
+
def format_user_error_preview(exc: Exception, *, max_len: int = 200) -> str:
"""Truncate a user-facing error string for short chat replies."""
return get_user_facing_error_message(exc)[:max_len]
diff --git a/providers/error_mapping.py b/providers/error_mapping.py
index 67bb177c..f51475d9 100644
--- a/providers/error_mapping.py
+++ b/providers/error_mapping.py
@@ -21,6 +21,10 @@ def user_visible_message_for_mapped_provider_error(
read_timeout_s: float | None,
) -> str:
"""Return the user-visible string after :func:`map_error` (405 + mapped types)."""
+ if getattr(mapped, "status_code", None) == 408:
+ return get_user_facing_error_message(
+ APIError("_", status_code=408), read_timeout_s=read_timeout_s
+ )
if getattr(mapped, "status_code", None) == 405:
return (
f"Upstream provider {provider_name} rejected the request method "
@@ -41,13 +45,27 @@ def map_error(
message = get_user_facing_error_message(e)
limiter = rate_limiter or GlobalRateLimiter.get_instance()
+ if isinstance(e, openai.APITimeoutError | httpx.TimeoutException):
+ return APIError(message, status_code=408, raw_error=str(e))
+ if isinstance(e, openai.APIConnectionError | httpx.ConnectError):
+ return APIError(message, raw_error=str(e))
+ if isinstance(e, httpx.ProtocolError):
+ return APIError(message, raw_error=str(e))
if isinstance(e, openai.AuthenticationError):
return AuthenticationError(message, raw_error=str(e))
+ if isinstance(e, openai.PermissionDeniedError):
+ return AuthenticationError(message, status_code=403, raw_error=str(e))
if isinstance(e, openai.RateLimitError):
limiter.set_blocked(60)
return RateLimitError(message, raw_error=str(e))
if isinstance(e, openai.BadRequestError):
return InvalidRequestError(message, raw_error=str(e))
+ if isinstance(e, openai.ConflictError):
+ return InvalidRequestError(message, status_code=409, raw_error=str(e))
+ if isinstance(e, openai.UnprocessableEntityError):
+ return InvalidRequestError(message, status_code=422, raw_error=str(e))
+ if isinstance(e, openai.NotFoundError):
+ return APIError(message, status_code=404, raw_error=str(e))
if isinstance(e, openai.InternalServerError):
raw_message = str(e)
sdk_status = getattr(e, "status_code", None)
@@ -69,12 +87,14 @@ def map_error(
if isinstance(e, httpx.HTTPStatusError):
status = e.response.status_code
if status in (401, 403):
- return AuthenticationError(message, raw_error=str(e))
+ return AuthenticationError(message, status_code=status, raw_error=str(e))
if status == 429:
limiter.set_blocked(60)
return RateLimitError(message, raw_error=str(e))
- if status == 400:
- return InvalidRequestError(message, raw_error=str(e))
+ if status in (400, 409, 422):
+ return InvalidRequestError(message, status_code=status, raw_error=str(e))
+ if status == 408:
+ return APIError(message, status_code=status, raw_error=str(e))
if status >= 500:
if status in (502, 503, 504):
return OverloadedError(message, raw_error=str(e))
diff --git a/providers/exceptions.py b/providers/exceptions.py
index 31d80d39..b004ec82 100644
--- a/providers/exceptions.py
+++ b/providers/exceptions.py
@@ -33,10 +33,10 @@ class ProviderError(Exception):
class AuthenticationError(ProviderError):
"""Raised when API key is invalid or missing."""
- def __init__(self, message: str, raw_error: Any = None):
+ def __init__(self, message: str, status_code: int = 401, raw_error: Any = None):
super().__init__(
message,
- status_code=401,
+ status_code=status_code,
error_type="authentication_error",
raw_error=raw_error,
)
@@ -45,10 +45,10 @@ class AuthenticationError(ProviderError):
class InvalidRequestError(ProviderError):
"""Raised when the request parameters are invalid."""
- def __init__(self, message: str, raw_error: Any = None):
+ def __init__(self, message: str, status_code: int = 400, raw_error: Any = None):
super().__init__(
message,
- status_code=400,
+ status_code=status_code,
error_type="invalid_request_error",
raw_error=raw_error,
)
diff --git a/tests/providers/test_anthropic_messages.py b/tests/providers/test_anthropic_messages.py
index 1cb57cb5..37d123d4 100644
--- a/tests/providers/test_anthropic_messages.py
+++ b/tests/providers/test_anthropic_messages.py
@@ -236,6 +236,48 @@ async def test_stream_maps_non_200_to_error_event_and_closes_response(
assert "REQ_123" in blob
+ ("status_code", "expected"),
+ [
+ (403, "model access"),
+ (404, "configured provider model"),
+ (408, "timed out after 600s"),
+ (409, "conflict"),
+ (422, "unsupported request content"),
+ (429, "rate limit"),
+ (500, "HTTP 500"),
+ ],
+)
+async def test_stream_maps_provider_status_to_actionable_error_event(
+ provider_config,
+ status_code,
+ expected,
+):
+ provider = NativeProvider(provider_config)
+ req = MockRequest()
+ response = FakeResponse(status_code=status_code, text="SECRET_UPSTREAM_BODY")
+
+ with (
+ patch.object(provider._client, "build_request", return_value=MagicMock()),
+ patch.object(
+ provider._client,
+ "send",
+ new_callable=AsyncMock,
+ return_value=response,
+ ),
+ ):
+ events = [
+ event async for event in provider.stream_response(req, request_id="REQ_X")
+ ]
+
+ assert response.is_closed
+ assert_canonical_stream_error_envelope(events, user_message_substr=expected)
+ blob = "".join(events)
+ assert "SECRET_UPSTREAM_BODY" not in blob
+ assert "REQ_X" in blob
+
+
@pytest.mark.asyncio
async def test_midstream_error_closes_open_block_and_uses_fresh_content_index(
provider_config,
diff --git a/tests/providers/test_anthropic_messages_429_retry.py b/tests/providers/test_anthropic_messages_429_retry.py
index 064ee97c..ff9026e7 100644
--- a/tests/providers/test_anthropic_messages_429_retry.py
+++ b/tests/providers/test_anthropic_messages_429_retry.py
@@ -138,9 +138,9 @@ async def test_native_stream_retries_on_http_5xx_then_streams(
("status_code", "substr"),
[
(500, "Provider API request failed"),
- (502, "Provider is currently overloaded"),
- (503, "Provider is currently overloaded"),
- (504, "Provider is currently overloaded"),
+ (502, "Provider is temporarily unavailable"),
+ (503, "Provider is temporarily unavailable"),
+ (504, "Provider is temporarily unavailable"),
],
)
@pytest.mark.asyncio
diff --git a/tests/providers/test_error_mapping.py b/tests/providers/test_error_mapping.py
index 1177a2f6..94ecdb7d 100644
--- a/tests/providers/test_error_mapping.py
+++ b/tests/providers/test_error_mapping.py
@@ -3,9 +3,10 @@
from pathlib import Path
from unittest.mock import MagicMock, patch
+import httpx
import openai
import pytest
-from httpx import ReadTimeout, Request, Response
+from httpx import HTTPStatusError, ReadTimeout, Request, Response
from core.anthropic import (
append_request_id,
@@ -37,6 +38,12 @@ def _make_openai_error(cls, message="test error", status_code=None):
return cls(message, response=response, body=body)
+def _make_http_status_error(status_code: int, message: str = "upstream error"):
+ request = Request("POST", "http://test")
+ response = Response(status_code=status_code, request=request)
+ return HTTPStatusError(message, request=request, response=response)
+
+
class TestMapError:
"""Tests for map_error function."""
@@ -65,6 +72,109 @@ class TestMapError:
assert isinstance(result, InvalidRequestError)
assert result.status_code == 400
+ @pytest.mark.parametrize(
+ ("error_cls", "status_code", "result_cls", "message_substr"),
+ [
+ (
+ openai.PermissionDeniedError,
+ 403,
+ AuthenticationError,
+ "model access",
+ ),
+ (
+ openai.NotFoundError,
+ 404,
+ APIError,
+ "configured provider model",
+ ),
+ (openai.ConflictError, 409, InvalidRequestError, "conflict"),
+ (
+ openai.UnprocessableEntityError,
+ 422,
+ InvalidRequestError,
+ "unsupported request content",
+ ),
+ ],
+ )
+ def test_openai_status_errors_map_to_safe_specific_messages(
+ self, error_cls, status_code, result_cls, message_substr
+ ):
+ exc = _make_openai_error(error_cls, status_code=status_code)
+ result = map_error(exc)
+ assert isinstance(result, result_cls)
+ assert result.status_code == status_code
+ assert message_substr in result.message
+
+ @pytest.mark.parametrize(
+ ("exc", "message_substr"),
+ [
+ (
+ openai.APITimeoutError(request=Request("POST", "http://test")),
+ "timed out",
+ ),
+ (
+ openai.APIConnectionError(request=Request("POST", "http://test")),
+ "Could not connect",
+ ),
+ (
+ httpx.ConnectError("boom", request=Request("POST", "http://test")),
+ "Could not connect",
+ ),
+ (
+ httpx.RemoteProtocolError(
+ "closed", request=Request("POST", "http://test")
+ ),
+ "interrupted",
+ ),
+ ],
+ )
+ def test_transport_errors_map_to_safe_specific_messages(self, exc, message_substr):
+ result = map_error(exc)
+ assert isinstance(result, APIError)
+ assert message_substr in result.message
+
+ def test_http_403_preserves_authorization_context(self):
+ """HTTP 403 stays distinguishable from missing/invalid API key errors."""
+ exc = _make_http_status_error(403, "Forbidden")
+ result = map_error(exc)
+ assert isinstance(result, AuthenticationError)
+ assert result.status_code == 403
+ assert "model access" in result.message
+
+ def test_http_404_mentions_configured_model(self):
+ """Removed provider models should produce an actionable user message."""
+ exc = _make_http_status_error(404, "Not Found")
+ result = map_error(exc)
+ assert isinstance(result, APIError)
+ assert result.status_code == 404
+ assert "configured provider model" in result.message
+
+ @pytest.mark.parametrize(
+ ("status_code", "result_cls", "message_substr"),
+ [
+ (400, InvalidRequestError, "Invalid request"),
+ (408, APIError, "timed out"),
+ (409, InvalidRequestError, "conflict"),
+ (422, InvalidRequestError, "unsupported request content"),
+ (429, RateLimitError, "rate limit"),
+ (500, APIError, "HTTP 500"),
+ (599, APIError, "HTTP 599"),
+ ],
+ )
+ def test_http_status_errors_map_to_safe_specific_messages(
+ self, status_code, result_cls, message_substr
+ ):
+ exc = _make_http_status_error(status_code)
+ with patch("providers.error_mapping.GlobalRateLimiter") as mock_rl:
+ mock_instance = MagicMock()
+ mock_rl.get_instance.return_value = mock_instance
+ result = map_error(exc)
+ assert isinstance(result, result_cls)
+ assert result.status_code == status_code
+ assert message_substr in result.message
+ if status_code == 429:
+ mock_instance.set_blocked.assert_called_once_with(60)
+
@pytest.mark.parametrize(
"message",
["Server overloaded", "No capacity available"],
@@ -141,6 +251,46 @@ def test_user_facing_message_read_timeout_empty_string():
assert message == "Provider request timed out after 60s."
+def test_user_facing_message_http_status_error_includes_status():
+ exc = _make_http_status_error(500, "Server Error")
+ assert get_user_facing_error_message(exc) == (
+ "Provider API request failed (HTTP 500)."
+ )
+
+
+ ("status_code", "expected"),
+ [
+ (400, "Invalid request sent to provider."),
+ (401, "Provider authentication failed. Check API key."),
+ (
+ 403,
+ "Provider authorization failed (HTTP 403). Check API key, account "
+ "permissions, or model access.",
+ ),
+ (
+ 404,
+ "Provider endpoint or model was not found (HTTP 404). Check the "
+ "configured provider model.",
+ ),
+ (408, "Provider request timed out after 60s."),
+ (409, "Provider rejected the request due to a conflict (HTTP 409)."),
+ (422, "Provider rejected unsupported request content (HTTP 422)."),
+ (429, "Provider rate limit reached. Please retry shortly."),
+ (502, "Provider is temporarily unavailable. Please retry."),
+ (599, "Provider API request failed (HTTP 599)."),
+ ],
+)
+def test_user_facing_message_http_status_matrix(status_code, expected):
+ exc = _make_http_status_error(status_code)
+ assert get_user_facing_error_message(exc, read_timeout_s=60) == expected
+
+
+def test_user_facing_message_mapped_provider_error_uses_safe_message():
+ mapped = APIError("Could not connect to provider.")
+ assert get_user_facing_error_message(mapped) == "Could not connect to provider."
+
+
def test_append_request_id_suffix():
"""Request id suffix should be appended deterministically."""
message = append_request_id("Provider request failed.", "req_abc123")
diff --git a/tests/providers/test_llamacpp.py b/tests/providers/test_llamacpp.py
index df87069d..860d38de 100644
--- a/tests/providers/test_llamacpp.py
+++ b/tests/providers/test_llamacpp.py
@@ -285,7 +285,7 @@ async def test_stream_network_error(llamacpp_provider):
blob = "".join(events)
assert_canonical_stream_error_envelope(
- events, user_message_substr="Connection refused"
+ events, user_message_substr="Could not connect to provider"
)
assert "TEST_ID2" in blob
diff --git a/tests/providers/test_lmstudio.py b/tests/providers/test_lmstudio.py
index 06aca7a6..acd17b03 100644
--- a/tests/providers/test_lmstudio.py
+++ b/tests/providers/test_lmstudio.py
@@ -316,7 +316,7 @@ async def test_stream_network_error(lmstudio_provider):
blob = "".join(events)
assert_canonical_stream_error_envelope(
- events, user_message_substr="Connection refused"
+ events, user_message_substr="Could not connect to provider"
)
assert "TEST_ID2" in blob
diff --git a/tests/providers/test_openai_compat_5xx_retry.py b/tests/providers/test_openai_compat_5xx_retry.py
index 0faa8392..316ab66b 100644
--- a/tests/providers/test_openai_compat_5xx_retry.py
+++ b/tests/providers/test_openai_compat_5xx_retry.py
@@ -13,6 +13,14 @@ from providers.rate_limit import GlobalRateLimiter
from tests.providers.test_nvidia_nim import MockRequest
+def _openai_status_error(cls, code: int, message: str = "upstream error"):
+ return cls(
+ message,
+ response=Response(code, request=Request("POST", "http://x")),
+ body={"error": {"message": "SECRET_UPSTREAM_BODY"}},
+ )
+
+
def _internal_5xx(code: int) -> openai.InternalServerError:
return openai.InternalServerError(
"unavailable",
@@ -67,6 +75,57 @@ async def test_nim_stream_retries_on_openai_5xx_then_streams(status_code):
GlobalRateLimiter.reset_instance()
+ ("error_cls", "status_code", "expected"),
+ [
+ (openai.PermissionDeniedError, 403, "model access"),
+ (openai.NotFoundError, 404, "configured provider model"),
+ (openai.ConflictError, 409, "conflict"),
+ (openai.UnprocessableEntityError, 422, "unsupported request content"),
+ ],
+)
+async def test_nim_stream_openai_status_errors_emit_actionable_user_message(
+ error_cls,
+ status_code,
+ expected,
+):
+ GlobalRateLimiter.reset_instance()
+ try:
+ config = ProviderConfig(
+ api_key="test_key",
+ base_url="https://test.api.nvidia.com/v1",
+ rate_limit=100,
+ rate_window=60,
+ http_read_timeout=600.0,
+ http_write_timeout=15.0,
+ http_connect_timeout=5.0,
+ )
+ provider = NvidiaNimProvider(config, nim_settings=NimSettings())
+ req = MockRequest()
+
+ with patch.object(
+ provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ ) as mock_create:
+ mock_create.side_effect = _openai_status_error(error_cls, status_code)
+ events = [
+ event
+ async for event in provider.stream_response(
+ req, request_id="REQ_OPENAI_STATUS"
+ )
+ ]
+
+ assert mock_create.await_count == 1
+ blob = "".join(events)
+ assert expected in blob
+ assert "SECRET_UPSTREAM_BODY" not in blob
+ assert "REQ_OPENAI_STATUS" in blob
+ finally:
+ GlobalRateLimiter.reset_instance()
+
+
@pytest.mark.parametrize(
("status_code", "expect_substr"),
[