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.pyindex 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_messageif 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.pyindex 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_codeif 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.pyindex 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.pyindex 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.asyncioasync 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.pyindex 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.asynciodiff --git a/tests/providers/test_error_mapping.py b/tests/providers/test_error_mapping.pyindex 1177a2f6..94ecdb7d 100644--- a/tests/providers/test_error_mapping.py+++ b/tests/providers/test_error_mapping.py@@ -3,9 +3,10 @@from pathlib import Pathfrom unittest.mock import MagicMock, patch+import httpximport openaiimport pytest-from httpx import ReadTimeout, Request, Response+from httpx import HTTPStatusError, ReadTimeout, Request, Responsefrom 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.pyindex 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 blobdiff --git a/tests/providers/test_lmstudio.py b/tests/providers/test_lmstudio.pyindex 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 blobdiff --git a/tests/providers/test_openai_compat_5xx_retry.py b/tests/providers/test_openai_compat_5xx_retry.pyindex 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 GlobalRateLimiterfrom 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"),[