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
Surface upstream provider errors
Alishahryar1885c26d97719
diff --git a/config/constants.py b/config/constants.pyindex 987027ae..c87425ec 100644--- a/config/constants.py+++ b/config/constants.py@@ -8,3 +8,6 @@ ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS = 81920# Max bytes read from a non-200 native messages response when verbose error logging is on.NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES = 4096++# Max upstream error bytes shown to users for copy/paste diagnostics.+PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES = 16384diff --git a/providers/anthropic_messages.py b/providers/anthropic_messages.pyindex 89a18e3a..1f43d58c 100644--- a/providers/anthropic_messages.py+++ b/providers/anthropic_messages.py@@ -12,6 +12,7 @@ from loguru import loggerfrom config.constants import (ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES,+ PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES,)from core.anthropic import iter_provider_stream_error_sse_eventsfrom core.anthropic.emitted_sse_tracker import EmittedNativeSseTracker@@ -25,6 +26,8 @@ from core.anthropic.native_sse_block_policy import (from core.trace import provider_native_messages_body_snapshot, trace_eventfrom providers.base import BaseProvider, ProviderConfigfrom providers.error_mapping import (+ attach_provider_error_body,+ extract_provider_error_detail,map_error,user_visible_message_for_mapped_provider_error,)@@ -166,19 +169,22 @@ class AnthropicMessagesTransport(BaseProvider):try:response.raise_for_status()except httpx.HTTPStatusError as error:+ preview, truncated = await self._read_error_body_preview(+ response, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES+ )+ attach_provider_error_body(error, preview, truncated=truncated)if self._config.log_api_error_tracebacks:- preview, truncated = await self._read_error_body_preview(- response, NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES- )- if preview:- text = preview.decode("utf-8", errors="replace")+ log_preview = preview[:NATIVE_MESSAGES_ERROR_BODY_LOG_CAP_BYTES]+ log_truncated = truncated or len(preview) > len(log_preview)+ if log_preview:+ text = log_preview.decode("utf-8", errors="replace")logger.error("{}_ERROR:{} HTTP {} body_preview_bytes={} truncated={}: {}",self._provider_name,req_tag,response.status_code,- len(preview),- truncated,+ len(log_preview),+ log_truncated,text,)else:@@ -191,12 +197,18 @@ class AnthropicMessagesTransport(BaseProvider):else:cl = response.headers.get("content-length", "").strip()extra = f" content_length_declared={cl}" if cl.isdigit() else ""+ body_extra = (+ " empty_error_body"+ if not preview+ else f" error_body_bytes_read={len(preview)}"+ )logger.error(- "{}_ERROR:{} HTTP {}{}",+ "{}_ERROR:{} HTTP {}{}{}",self._provider_name,req_tag,response.status_code,extra,+ body_extra,)raise error@@ -266,12 +278,6 @@ class AnthropicMessagesTransport(BaseProvider):)return event- def _format_error_message(self, base_message: str, request_id: str | None) -> str:- """Apply provider-specific request-id formatting to an error message."""- if request_id:- return f"{base_message}\nRequest ID: {request_id}"- return base_message-def _get_error_message(self, error: Exception, request_id: str | None) -> str:"""Map an exception into a user-facing provider error message."""mapped_error = map_error(error, rate_limiter=self._global_rate_limiter)@@ -279,8 +285,10 @@ class AnthropicMessagesTransport(BaseProvider):mapped_error,provider_name=self._provider_name,read_timeout_s=self._config.http_read_timeout,+ detail=extract_provider_error_detail(error),+ request_id=request_id,)- return self._format_error_message(base_message, request_id)+ return base_messagedef _emit_error_events(self,diff --git a/providers/error_mapping.py b/providers/error_mapping.pyindex 67bb177c..cc4b8883 100644--- a/providers/error_mapping.py+++ b/providers/error_mapping.py@@ -1,8 +1,13 @@-"""Provider-specific exception mapping."""+"""Provider-specific exception mapping and user-visible diagnostics."""++import json+from dataclasses import dataclass+from typing import Anyimport httpximport openai+from config.constants import PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTESfrom core.anthropic import get_user_facing_error_messagefrom providers.exceptions import (APIError,@@ -13,14 +18,234 @@ from providers.exceptions import ()from providers.rate_limit import GlobalRateLimiter+_BODY_ATTR = "_fcc_provider_error_body"+_BODY_TRUNCATED_ATTR = "_fcc_provider_error_body_truncated"+++@dataclass(frozen=True)+class ProviderErrorDetail:+ """Structured upstream error detail surfaced directly to users."""++ status_code: int | None = None+ body_text: str | None = None+ exception_text: str | None = None+ error_type_hint: str | None = None+ body_truncated: bool = False+++def attach_provider_error_body(+ exc: Exception, body: bytes | str, *, truncated: bool = False+) -> None:+ """Attach a streamed HTTP error body to an exception for later formatting."""+ setattr(exc, _BODY_ATTR, body)+ setattr(exc, _BODY_TRUNCATED_ATTR, truncated)+++def _status_code_from_exception(exc: Exception) -> int | None:+ status = getattr(exc, "status_code", None)+ if isinstance(status, int):+ return status+ response = getattr(exc, "response", None)+ response_status = getattr(response, "status_code", None)+ if isinstance(response_status, int):+ return response_status+ return None+++def _body_from_response(exc: Exception) -> Any:+ response = getattr(exc, "response", None)+ if response is None:+ return None+ try:+ return response.json()+ except ValueError, RuntimeError:+ pass+ try:+ return response.text+ except httpx.ResponseNotRead, RuntimeError:+ return None+++def _normalize_body_text(body: Any) -> str | None:+ if body is None:+ return None+ if isinstance(body, bytes):+ text = body.decode("utf-8", errors="replace")+ elif isinstance(body, str):+ text = body+ else:+ try:+ return json.dumps(body, ensure_ascii=False, separators=(",", ":"))+ except TypeError:+ text = str(body)+ stripped = text.strip()+ if not stripped:+ return None+ try:+ parsed = json.loads(stripped)+ except ValueError:+ return stripped+ return json.dumps(parsed, ensure_ascii=False, separators=(",", ":"))+++def _cap_text_bytes(text: str, max_bytes: int) -> tuple[str, bool]:+ encoded = text.encode("utf-8", errors="replace")+ if len(encoded) <= max_bytes:+ return text, False+ capped = encoded[:max_bytes].decode("utf-8", errors="replace")+ return f"{capped}\n... [truncated after {max_bytes} bytes]", True+++def _error_type_hint_from_body(body: Any, body_text: str | None) -> str | None:+ parsed = body+ if isinstance(parsed, bytes):+ text = parsed.decode("utf-8", errors="replace")+ try:+ parsed = json.loads(text)+ except ValueError:+ parsed = None+ elif isinstance(parsed, str):+ try:+ parsed = json.loads(parsed)+ except ValueError:+ parsed = None+ if isinstance(parsed, dict):+ error = parsed.get("error")+ if isinstance(error, dict):+ for key in ("type", "code"):+ value = error.get(key)+ if isinstance(value, str) and value.strip():+ return value.strip()+ for key in ("type", "code"):+ value = parsed.get(key)+ if isinstance(value, str) and value.strip():+ return value.strip()+ if (+ body_text+ and "model" in body_text.lower()+ and "unsupported" in body_text.lower()+ ):+ return "upstream_model_error"+ return None+++def extract_provider_error_detail(exc: Exception) -> ProviderErrorDetail:+ """Extract copyable upstream status/body/exception detail from provider errors."""+ raw_body = getattr(exc, _BODY_ATTR, None)+ raw_body_truncated = bool(getattr(exc, _BODY_TRUNCATED_ATTR, False))+ if raw_body is None:+ raw_body = getattr(exc, "body", None)+ if raw_body is None:+ raw_body = _body_from_response(exc)++ body_text = _normalize_body_text(raw_body)+ display_truncated = raw_body_truncated+ if body_text is not None:+ body_text, cap_truncated = _cap_text_bytes(+ body_text, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES+ )+ display_truncated = display_truncated or cap_truncated++ exception_text = str(exc).strip() or None+ if exception_text is not None:+ exception_text, _ = _cap_text_bytes(+ exception_text, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES+ )++ return ProviderErrorDetail(+ status_code=_status_code_from_exception(exc),+ body_text=body_text,+ exception_text=exception_text,+ error_type_hint=_error_type_hint_from_body(raw_body, body_text),+ body_truncated=display_truncated,+ )+++def _provider_error_category(mapped: Exception) -> str | None:+ error_type = getattr(mapped, "error_type", None)+ if isinstance(error_type, str) and error_type.strip():+ return error_type.strip()+ return None+++def _append_request_id_lines(lines: list[str], request_id: str | None) -> None:+ if request_id:+ lines.extend(("", f"Request ID: {request_id}"))+++def format_provider_error_message(+ mapped: Exception,+ detail: ProviderErrorDetail,+ *,+ provider_name: str,+ read_timeout_s: float | None,+ request_id: str | None = None,+) -> str:+ """Return a copyable user-facing provider error including upstream detail."""+ stable_message = get_user_facing_error_message(+ mapped, read_timeout_s=read_timeout_s+ )+ has_upstream_detail = detail.status_code is not None or detail.body_text is not None+ if not has_upstream_detail:+ lines = [stable_message]+ if detail.exception_text and detail.exception_text != stable_message:+ lines.extend(("", "Provider exception:", detail.exception_text))+ _append_request_id_lines(lines, request_id)+ return "\n".join(lines)++ if detail.status_code == 405:+ lines = [+ f"Upstream provider {provider_name} rejected the request method "+ "or endpoint (HTTP 405)."+ ]+ elif detail.status_code is not None:+ lines = [+ f"Upstream provider {provider_name} returned HTTP {detail.status_code}."+ ]+ else:+ lines = [f"Upstream provider {provider_name} returned an error."]++ category = detail.error_type_hint or _provider_error_category(mapped)+ if category:+ lines.append(f"Category: {category}")+ if stable_message and stable_message != lines[0]:+ lines.append(f"Mapped message: {stable_message}")++ lines.extend(("", "Upstream error:"))+ if detail.body_text:+ lines.append(detail.body_text)+ else:+ lines.append("(empty upstream error body)")+ if detail.body_truncated and (+ detail.body_text is None+ or f"truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes"+ not in detail.body_text+ ):+ lines.append(+ f"... [truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes]"+ )++ _append_request_id_lines(lines, request_id)+ return "\n".join(lines)+def user_visible_message_for_mapped_provider_error(mapped: Exception,*,provider_name: str,read_timeout_s: float | None,+ detail: ProviderErrorDetail | None = None,+ request_id: str | None = None,) -> str:"""Return the user-visible string after :func:`map_error` (405 + mapped types)."""+ if detail is not None:+ return format_provider_error_message(+ mapped,+ detail,+ provider_name=provider_name,+ read_timeout_s=read_timeout_s,+ request_id=request_id,+ )if getattr(mapped, "status_code", None) == 405:return (f"Upstream provider {provider_name} rejected the request method "diff --git a/providers/open_router/client.py b/providers/open_router/client.pyindex 8ae584c1..84c98abe 100644--- a/providers/open_router/client.py+++ b/providers/open_router/client.py@@ -5,7 +5,7 @@ from __future__ import annotationsfrom collections.abc import Iteratorfrom typing import Any-from core.anthropic import append_request_id, iter_provider_stream_error_sse_events+from core.anthropic import iter_provider_stream_error_sse_eventsfrom core.anthropic.native_sse_block_policy import (NativeSseBlockPolicyState,is_terminal_openrouter_done_event,@@ -103,10 +103,6 @@ class OpenRouterProvider(AnthropicMessagesTransport):)return event- def _format_error_message(self, base_message: str, request_id: str | None) -> str:- """Keep OpenRouter's existing request-id suffix format."""- return append_request_id(base_message, request_id)-def _emit_error_events(self,*,diff --git a/providers/openai_compat.py b/providers/openai_compat.pyindex 6ec582e5..91b55055 100644--- a/providers/openai_compat.py+++ b/providers/openai_compat.py@@ -20,12 +20,12 @@ from core.anthropic import (HeuristicToolParser,SSEBuilder,ThinkTagParser,- append_request_id,map_stop_reason,)from core.trace import provider_chat_body_snapshot, trace_eventfrom providers.base import BaseProvider, ProviderConfigfrom providers.error_mapping import (+ extract_provider_error_detail,map_error,user_visible_message_for_mapped_provider_error,)@@ -466,8 +466,10 @@ class OpenAIChatTransport(BaseProvider):mapped_e,provider_name=tag,read_timeout_s=self._config.http_read_timeout,+ detail=extract_provider_error_detail(e),+ request_id=request_id,)- error_message = append_request_id(base_message, request_id)+ error_message = base_messagetrace_event(stage="provider",event="provider.response.error",diff --git a/tests/providers/test_anthropic_messages.py b/tests/providers/test_anthropic_messages.pyindex 1cb57cb5..c4fc462e 100644--- a/tests/providers/test_anthropic_messages.py+++ b/tests/providers/test_anthropic_messages.py@@ -230,9 +230,10 @@ async def test_stream_maps_non_200_to_error_event_and_closes_response(assert response.is_closedassert_canonical_stream_error_envelope(- events, user_message_substr="Provider API request failed"+ events, user_message_substr="Upstream provider TEST_NATIVE returned HTTP 500.")blob = "".join(events)+ assert "Internal Server Error" in blobassert "REQ_123" in blobdiff --git a/tests/providers/test_error_mapping.py b/tests/providers/test_error_mapping.pyindex 1177a2f6..f193a9d8 100644--- a/tests/providers/test_error_mapping.py+++ b/tests/providers/test_error_mapping.py@@ -5,14 +5,18 @@ from unittest.mock import MagicMock, patchimport openaiimport pytest-from httpx import ReadTimeout, Request, Response+from httpx import HTTPStatusError, ReadTimeout, Request, Response+from config.constants import PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTESfrom core.anthropic import (append_request_id,format_user_error_preview,get_user_facing_error_message,)from providers.error_mapping import (+ attach_provider_error_body,+ extract_provider_error_detail,+ format_provider_error_message,map_error,user_visible_message_for_mapped_provider_error,)@@ -170,6 +174,120 @@ def test_user_visible_message_for_mapped_provider_error_405():assert "ACME" in msg and "405" in msg+def test_openai_bad_request_body_is_user_visible():+ exc = _make_openai_error(+ openai.BadRequestError,+ message="Thinking mode does not support this tool_choice",+ status_code=400,+ )+ mapped = map_error(exc)+ msg = format_provider_error_message(+ mapped,+ extract_provider_error_detail(exc),+ provider_name="NIM",+ read_timeout_s=60.0,+ request_id="req_body",+ )++ assert "Upstream provider NIM returned HTTP 400." in msg+ assert "Category: invalid_request_error" in msg+ assert "Thinking mode does not support this tool_choice" in msg+ assert (+ '{"error":{"message":"Thinking mode does not support this tool_choice"}}' in msg+ )+ assert "Request ID: req_body" in msg+++def test_auth_status_with_model_error_body_is_not_only_check_api_key():+ body = {+ "type": "error",+ "error": {+ "type": "ModelError",+ "message": "Model qwen3.7-max is not supported for format oa-compat",+ },+ }+ exc = openai.AuthenticationError(+ "Unauthorized",+ response=Response(status_code=401, request=Request("POST", "http://test")),+ body=body,+ )+ mapped = map_error(exc)+ msg = format_provider_error_message(+ mapped,+ extract_provider_error_detail(exc),+ provider_name="OPENCODE_GO",+ read_timeout_s=60.0,+ request_id="req_model",+ )++ assert "Upstream provider OPENCODE_GO returned HTTP 401." in msg+ assert "Category: ModelError" in msg+ assert "Provider authentication failed. Check API key." in msg+ assert "Model qwen3.7-max is not supported for format oa-compat" in msg+ assert msg != "Provider authentication failed. Check API key."+++def test_http_status_error_json_body_is_compact_and_visible():+ response = Response(+ status_code=400,+ request=Request("POST", "http://test"),+ json={"error": {"type": "BadRequest", "message": "bad field"}},+ )+ exc = HTTPStatusError("Bad Request", request=response.request, response=response)+ mapped = map_error(exc)+ msg = user_visible_message_for_mapped_provider_error(+ mapped,+ provider_name="LOCAL",+ read_timeout_s=30.0,+ detail=extract_provider_error_detail(exc),+ request_id="req_json",+ )++ assert "Upstream provider LOCAL returned HTTP 400." in msg+ assert "Category: BadRequest" in msg+ assert '{"error":{"type":"BadRequest","message":"bad field"}}' in msg+ assert "Request ID: req_json" in msg+++def test_empty_http_error_body_is_explicitly_reported():+ response = Response(+ status_code=500,+ request=Request("POST", "http://test"),+ content=b"",+ )+ exc = HTTPStatusError("Server Error", request=response.request, response=response)+ mapped = map_error(exc)+ msg = format_provider_error_message(+ mapped,+ extract_provider_error_detail(exc),+ provider_name="EMPTY",+ read_timeout_s=30.0,+ )++ assert "Upstream provider EMPTY returned HTTP 500." in msg+ assert "(empty upstream error body)" in msg+++def test_attached_provider_error_body_is_capped_for_display():+ response = Response(+ status_code=500,+ request=Request("POST", "http://test"),+ content=b"",+ )+ exc = HTTPStatusError("Server Error", request=response.request, response=response)+ attach_provider_error_body(exc, "x" * (PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES + 10))+ mapped = map_error(exc)+ msg = format_provider_error_message(+ mapped,+ extract_provider_error_detail(exc),+ provider_name="LONG",+ read_timeout_s=30.0,+ )++ assert f"truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes" in msg+ assert "x" * 100 in msg++def test_streaming_transports_pass_scoped_rate_limiter_to_map_error():"""Guardrail: streaming adapters must scope reactive 429 handling per provider."""root = Path(__file__).resolve().parents[2]diff --git a/tests/providers/test_streaming_errors.py b/tests/providers/test_streaming_errors.pyindex 523057f1..362e4196 100644--- a/tests/providers/test_streaming_errors.py+++ b/tests/providers/test_streaming_errors.py@@ -5,6 +5,7 @@ from types import SimpleNamespacefrom unittest.mock import AsyncMock, MagicMock, patchimport httpx+import openaiimport pytestfrom config.nim import NimSettings@@ -203,7 +204,7 @@ class TestStreamingExceptionHandling:event_text = "".join(events)assert "timed out after" in event_text- assert "request_id=req_timeout123" in event_text+ assert "Request ID: req_timeout123" in event_textassert "message_stop" in event_text_assert_no_content_deltas_after_error_text(events, "timed out after")@@ -505,12 +506,100 @@ class TestStreamingExceptionHandling:"Upstream provider NIM rejected the request method or endpoint (HTTP 405)."in event_text)- assert "request_id=REQ405" in event_text+ assert "Request ID: REQ405" in event_text_assert_no_content_deltas_after_error_text(events,"Upstream provider NIM rejected the request method or endpoint (HTTP 405).",)+ @pytest.mark.asyncio+ async def test_stream_with_openai_bad_request_surfaces_upstream_body(self):+ """OpenAI SDK bodies should be emitted so users can copy exact provider errors."""+ provider = _make_provider()+ request = _make_request()+ response = httpx.Response(+ status_code=400,+ request=httpx.Request("POST", "https://example.com/v1/chat/completions"),+ )+ body = {+ "error": {+ "type": "BadRequest",+ "message": "Thinking mode does not support this tool_choice",+ }+ }+ error = openai.BadRequestError("Bad Request", response=response, body=body)++ with patch.object(+ provider._client.chat.completions,+ "create",+ new_callable=AsyncMock,+ side_effect=error,+ ):+ events = [+ e+ async for e in provider.stream_response(+ request,+ request_id="REQ_BODY",+ )+ ]++ event_text = "".join(events)+ message_text = "".join(+ str(ev.data.get("delta", {}).get("text", ""))+ for ev in parse_sse_text(event_text)+ if ev.event == "content_block_delta"+ and ev.data.get("delta", {}).get("type") == "text_delta"+ )+ assert "Upstream provider NIM returned HTTP 400." in event_text+ assert "Category: BadRequest" in event_text+ assert "Thinking mode does not support this tool_choice" in event_text+ assert (+ '{"error":{"type":"BadRequest","message":"Thinking mode does not support this tool_choice"}}'+ in message_text+ )+ assert "Request ID: REQ_BODY" in event_text+ _assert_no_content_deltas_after_error_text(+ events,+ "Upstream provider NIM returned HTTP 400.",+ )++ @pytest.mark.asyncio+ async def test_error_after_native_tool_call_top_level_error_includes_body(self):+ """After a tool_use block, detailed provider errors remain top-level SSE errors."""+ provider = _make_provider()+ request = _make_request()+ tool_chunk = _make_tool_calls_chunk(+ name="echo_smoke", arguments="{}", tool_id="call_body", index=0+ )+ response = httpx.Response(+ status_code=400,+ request=httpx.Request("POST", "https://example.com/v1/chat/completions"),+ )+ body = {"error": {"message": "bad after tool"}}+ error = openai.BadRequestError("Bad Request", response=response, body=body)+ stream_mock = AsyncStreamMock([tool_chunk], error=error)++ with patch.object(+ provider._client.chat.completions,+ "create",+ new_callable=AsyncMock,+ return_value=stream_mock,+ ):+ events = [+ e+ async for e in provider.stream_response(+ request,+ request_id="REQ_TOOL_BODY",+ )+ ]++ event_text = "".join(events)+ assert "tool_use" in event_text+ assert "event: error\n" in event_text+ assert "bad after tool" in event_text+ assert "Request ID: REQ_TOOL_BODY" in event_text+ _assert_error_not_in_text_deltas_after_tool(events, "bad after tool")+@pytest.mark.asyncioasync def test_stream_rate_limited_retries_via_execute_with_retry(self):"""When rate limited, execute_with_retry handles retries transparently."""