- implement new ModelAPIError superclass

- handle connection errors for bedrock and openai

Author: dsfaccini

docs/models/overview.md

@@ -180,7 +180,7 @@ contains all the exceptions encountered during the `run` execution.
 === "Python >=3.11"
 
     ```python {title="fallback_model_failure.py" py="3.11"}
-    from pydantic_ai import Agent, ModelHTTPError
+    from pydantic_ai import Agent, ModelAPIError
     from pydantic_ai.models.anthropic import AnthropicModel
     from pydantic_ai.models.fallback import FallbackModel
     from pydantic_ai.models.openai import OpenAIChatModel
@@ -192,7 +192,7 @@ contains all the exceptions encountered during the `run` execution.
     agent = Agent(fallback_model)
     try:
         response = agent.run_sync('What is the capital of France?')
-    except* ModelHTTPError as exc_group:
+    except* ModelAPIError as exc_group:
         for exc in exc_group.exceptions:
             print(exc)
     ```
@@ -206,7 +206,7 @@ contains all the exceptions encountered during the `run` execution.
     ```python {title="fallback_model_failure.py" noqa="F821" test="skip"}
     from exceptiongroup import catch
 
-    from pydantic_ai import Agent, ModelHTTPError
+    from pydantic_ai import Agent, ModelAPIError
     from pydantic_ai.models.anthropic import AnthropicModel
     from pydantic_ai.models.fallback import FallbackModel
     from pydantic_ai.models.openai import OpenAIChatModel
@@ -222,10 +222,11 @@ contains all the exceptions encountered during the `run` execution.
     fallback_model = FallbackModel(openai_model, anthropic_model)
 
     agent = Agent(fallback_model)
-    with catch({ModelHTTPError: model_status_error_handler}):
+    with catch({ModelAPIError: model_status_error_handler}):
         response = agent.run_sync('What is the capital of France?')
     ```
 
 By default, the `FallbackModel` only moves on to the next model if the current model raises a
+[`ModelAPIError`][pydantic_ai.exceptions.ModelAPIError], which includes
 [`ModelHTTPError`][pydantic_ai.exceptions.ModelHTTPError]. You can customize this behavior by
 passing a custom `fallback_on` argument to the `FallbackModel` constructor.

pydantic_ai_slim/pydantic_ai/__init__.py

@@ -24,6 +24,7 @@
     CallDeferred,
     FallbackExceptionGroup,
     IncompleteToolCall,
+    ModelAPIError,
     ModelHTTPError,
     ModelRetry,
     UnexpectedModelBehavior,
@@ -126,6 +127,7 @@
     'CallDeferred',
     'ApprovalRequired',
     'ModelRetry',
+    'ModelAPIError',
     'ModelHTTPError',
     'FallbackExceptionGroup',
     'IncompleteToolCall',

pydantic_ai_slim/pydantic_ai/exceptions.py

@@ -22,6 +22,7 @@
     'AgentRunError',
     'UnexpectedModelBehavior',
     'UsageLimitExceeded',
+    'ModelAPIError',
     'ModelHTTPError',
     'IncompleteToolCall',
     'FallbackExceptionGroup',
@@ -151,27 +152,31 @@ def __str__(self) -> str:
             return self.message
 
 
-class ModelHTTPError(AgentRunError):
-    """Raised when an model provider response has a status code of 4xx or 5xx."""
-
-    status_code: int
-    """The HTTP status code returned by the API."""
+class ModelAPIError(AgentRunError):
+    """Raised when a model provider API request fails."""
 
     model_name: str
     """The name of the model associated with the error."""
 
     body: object | None
     """The body of the response, if available."""
 
-    message: str
-    """The error message with the status code and response body, if available."""
+    def __init__(self, model_name: str, body: object | None = None, message: str | None = None):
+        self.model_name = model_name
+        self.body = body
+        super().__init__(message or f'model_name: {model_name}, body: {body}')
+
+
+class ModelHTTPError(ModelAPIError):
+    """Raised when an model provider response has a status code of 4xx or 5xx."""
+
+    status_code: int
+    """The HTTP status code returned by the API."""
 
     def __init__(self, status_code: int, model_name: str, body: object | None = None):
         self.status_code = status_code
-        self.model_name = model_name
-        self.body = body
         message = f'status_code: {status_code}, model_name: {model_name}, body: {body}'
-        super().__init__(message)
+        super().__init__(model_name=model_name, body=body, message=message)
 
 
 class FallbackExceptionGroup(ExceptionGroup[Any]):

pydantic_ai_slim/pydantic_ai/models/bedrock.py

@@ -41,7 +41,7 @@
     usage,
 )
 from pydantic_ai._run_context import RunContext
-from pydantic_ai.exceptions import ModelHTTPError, UserError
+from pydantic_ai.exceptions import ModelAPIError, ModelHTTPError, UserError
 from pydantic_ai.models import Model, ModelRequestParameters, StreamedResponse, download_item
 from pydantic_ai.providers import Provider, infer_provider
 from pydantic_ai.providers.bedrock import BedrockModelProfile
@@ -312,8 +312,10 @@ async def count_tokens(
         try:
             response = await anyio.to_thread.run_sync(functools.partial(self.client.count_tokens, **params))
         except ClientError as e:
-            status_code = e.response.get('ResponseMetadata', {}).get('HTTPStatusCode', 500)
-            raise ModelHTTPError(status_code=status_code, model_name=self.model_name, body=e.response) from e
+            status_code = e.response.get('ResponseMetadata', {}).get('HTTPStatusCode')
+            if isinstance(status_code, int):
+                raise ModelHTTPError(status_code=status_code, model_name=self.model_name, body=e.response) from e
+            raise ModelAPIError(model_name=self.model_name, body=e.response) from e
         return usage.RequestUsage(input_tokens=response['inputTokens'])
 
     @asynccontextmanager
@@ -459,8 +461,10 @@ async def _messages_create(
             else:
                 model_response = await anyio.to_thread.run_sync(functools.partial(self.client.converse, **params))
         except ClientError as e:
-            status_code = e.response.get('ResponseMetadata', {}).get('HTTPStatusCode', 500)
-            raise ModelHTTPError(status_code=status_code, model_name=self.model_name, body=e.response) from e
+            status_code = e.response.get('ResponseMetadata', {}).get('HTTPStatusCode')
+            if isinstance(status_code, int):
+                raise ModelHTTPError(status_code=status_code, model_name=self.model_name, body=e.response) from e
+            raise ModelAPIError(model_name=self.model_name, body=e.response) from e
         return model_response
 
     @staticmethod

pydantic_ai_slim/pydantic_ai/models/fallback.py

@@ -11,7 +11,7 @@
 from pydantic_ai._run_context import RunContext
 from pydantic_ai.models.instrumented import InstrumentedModel
 
-from ..exceptions import FallbackExceptionGroup, ModelHTTPError
+from ..exceptions import FallbackExceptionGroup, ModelAPIError
 from ..profiles import ModelProfile
 from . import KnownModelName, Model, ModelRequestParameters, StreamedResponse, infer_model
 
@@ -36,7 +36,7 @@ def __init__(
         self,
         default_model: Model | KnownModelName | str,
         *fallback_models: Model | KnownModelName | str,
-        fallback_on: Callable[[Exception], bool] | tuple[type[Exception], ...] = (ModelHTTPError,),
+        fallback_on: Callable[[Exception], bool] | tuple[type[Exception], ...] = (ModelAPIError,),
     ):
         """Initialize a fallback model instance.
 

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -13,7 +13,7 @@
 from pydantic_core import to_json
 from typing_extensions import assert_never, deprecated
 
-from .. import ModelHTTPError, UnexpectedModelBehavior, _utils, usage
+from .. import ModelAPIError, ModelHTTPError, UnexpectedModelBehavior, _utils, usage
 from .._output import DEFAULT_OUTPUT_TOOL_NAME, OutputObjectDefinition
 from .._run_context import RunContext
 from .._thinking_part import split_content_into_text_and_thinking
@@ -547,7 +547,7 @@ async def _completions_create(
                 raise ModelHTTPError(status_code=status_code, model_name=self.model_name, body=e.body) from e
             raise  # pragma: lax no cover
         except APIConnectionError as e:
-            raise ModelHTTPError(status_code=0, model_name=self.model_name, body=str(e)) from e
+            raise ModelAPIError(model_name=self.model_name, body=str(e)) from e
 
     def _process_response(self, response: chat.ChatCompletion | str) -> ModelResponse:
         """Process a non-streamed response, and prepare a message to return."""
@@ -1255,7 +1255,7 @@ async def _responses_create(
                 raise ModelHTTPError(status_code=status_code, model_name=self.model_name, body=e.body) from e
             raise  # pragma: lax no cover
         except APIConnectionError as e:
-            raise ModelHTTPError(status_code=0, model_name=self.model_name, body=str(e)) from e
+            raise ModelAPIError(model_name=self.model_name, body=str(e)) from e
 
     def _get_reasoning(self, model_settings: OpenAIResponsesModelSettings) -> Reasoning | Omit:
         reasoning_effort = model_settings.get('openai_reasoning_effort', None)

tests/models/test_bedrock.py

@@ -1,9 +1,11 @@
 from __future__ import annotations as _annotations
 
 import datetime
+from types import SimpleNamespace
 from typing import Any
 
 import pytest
+from botocore.exceptions import ClientError
 from inline_snapshot import snapshot
 from typing_extensions import TypedDict
 
@@ -33,11 +35,13 @@
     VideoUrl,
 )
 from pydantic_ai.agent import Agent
-from pydantic_ai.exceptions import ModelHTTPError, ModelRetry, UsageLimitExceeded
+from pydantic_ai.exceptions import ModelAPIError, ModelHTTPError, ModelRetry, UsageLimitExceeded
 from pydantic_ai.messages import AgentStreamEvent
 from pydantic_ai.models import ModelRequestParameters
 from pydantic_ai.models.bedrock import BedrockConverseModel, BedrockModelSettings
 from pydantic_ai.models.openai import OpenAIResponsesModel, OpenAIResponsesModelSettings
+from pydantic_ai.profiles import DEFAULT_PROFILE
+from pydantic_ai.providers import Provider
 from pydantic_ai.providers.bedrock import BedrockProvider
 from pydantic_ai.providers.openai import OpenAIProvider
 from pydantic_ai.run import AgentRunResult, AgentRunResultEvent
@@ -56,6 +60,53 @@
 ]
 
 
+class _StubBedrockClient:
+    """Minimal Bedrock client that always raises the provided error."""
+
+    def __init__(self, error: ClientError):
+        self._error = error
+        self.meta = SimpleNamespace(endpoint_url='https://bedrock.stub')
+
+    def converse(self, **_: Any) -> None:
+        raise self._error
+
+    def converse_stream(self, **_: Any) -> None:
+        raise self._error
+
+    def count_tokens(self, **_: Any) -> None:
+        raise self._error
+
+
+class _StubBedrockProvider(Provider[Any]):
+    """Provider implementation backed by the stub client."""
+
+    def __init__(self, client: _StubBedrockClient):
+        self._client = client
+
+    @property
+    def name(self) -> str:
+        return 'bedrock-stub'
+
+    @property
+    def base_url(self) -> str:
+        return 'https://bedrock.stub'
+
+    @property
+    def client(self) -> _StubBedrockClient:
+        return self._client
+
+    def model_profile(self, model_name: str):
+        return DEFAULT_PROFILE
+
+
+def _bedrock_model_with_client_error(error: ClientError) -> BedrockConverseModel:
+    """Instantiate a BedrockConverseModel wired to always raise the given error."""
+    return BedrockConverseModel(
+        'us.amazon.nova-micro-v1:0',
+        provider=_StubBedrockProvider(_StubBedrockClient(error)),
+    )
+
+
 async def test_bedrock_model(allow_model_requests: None, bedrock_provider: BedrockProvider):
     model = BedrockConverseModel('us.amazon.nova-micro-v1:0', provider=bedrock_provider)
     assert model.base_url == 'https://bedrock-runtime.us-east-1.amazonaws.com'
@@ -153,6 +204,28 @@ async def test_bedrock_count_tokens_error(allow_model_requests: None, bedrock_pr
     assert exc_info.value.body.get('Error', {}).get('Message') == 'The provided model identifier is invalid.'  # type: ignore[union-attr]
 
 
+async def test_bedrock_request_non_http_error():
+    error = ClientError({'Error': {'Code': 'TestException', 'Message': 'broken connection'}}, 'converse')
+    model = _bedrock_model_with_client_error(error)
+    params = ModelRequestParameters()
+
+    with pytest.raises(ModelAPIError) as exc_info:
+        await model.request([ModelRequest.user_text_prompt('hi')], None, params)
+
+    assert exc_info.value.body == error.response
+
+
+async def test_bedrock_count_tokens_non_http_error():
+    error = ClientError({'Error': {'Code': 'TestException', 'Message': 'broken connection'}}, 'count_tokens')
+    model = _bedrock_model_with_client_error(error)
+    params = ModelRequestParameters()
+
+    with pytest.raises(ModelAPIError) as exc_info:
+        await model.count_tokens([ModelRequest.user_text_prompt('hi')], None, params)
+
+    assert exc_info.value.body == error.response
+
+
 @pytest.mark.parametrize(
     ('model_name', 'expected'),
     [

tests/models/test_fallback.py

@@ -15,6 +15,7 @@
 
 from pydantic_ai import (
     Agent,
+    ModelAPIError,
     ModelHTTPError,
     ModelMessage,
     ModelProfile,
@@ -572,7 +573,7 @@ async def test_fallback_condition_tuple() -> None:
 
 async def test_fallback_connection_error() -> None:
     def connection_error_response(_model_messages: list[ModelMessage], _agent_info: AgentInfo) -> ModelResponse:
-        raise ModelHTTPError(status_code=0, model_name='test-connection-model', body='Connection timed out')
+        raise ModelAPIError(model_name='test-connection-model', body='Connection timed out')
 
     connection_error_model = FunctionModel(connection_error_response)
     fallback_model = FallbackModel(connection_error_model, success_model)

tests/models/test_openai.py

@@ -20,6 +20,7 @@
     CachePoint,
     DocumentUrl,
     ImageUrl,
+    ModelAPIError,
     ModelHTTPError,
     ModelProfile,
     ModelRequest,
@@ -1155,9 +1156,8 @@ def test_model_connection_error(allow_model_requests: None) -> None:
     )
     m = OpenAIChatModel('gpt-4o', provider=OpenAIProvider(openai_client=mock_client))
     agent = Agent(m)
-    with pytest.raises(ModelHTTPError) as exc_info:
+    with pytest.raises(ModelAPIError) as exc_info:
         agent.run_sync('hello')
-    assert exc_info.value.status_code == 0
     assert exc_info.value.model_name == 'gpt-4o'
     assert 'Connection to http://localhost:11434/v1 timed out' in str(exc_info.value.body)
 

tests/test_exceptions.py

@@ -11,6 +11,7 @@
     ApprovalRequired,
     CallDeferred,
     IncompleteToolCall,
+    ModelAPIError,
     ModelHTTPError,
     UnexpectedModelBehavior,
     UsageLimitExceeded,
@@ -28,6 +29,7 @@
         lambda: AgentRunError('test'),
         lambda: UnexpectedModelBehavior('test'),
         lambda: UsageLimitExceeded('test'),
+        lambda: ModelAPIError('model'),
         lambda: ModelHTTPError(500, 'model'),
         lambda: IncompleteToolCall('test'),
     ],
@@ -39,6 +41,7 @@
         'AgentRunError',
         'UnexpectedModelBehavior',
         'UsageLimitExceeded',
+        'ModelAPIError',
         'ModelHTTPError',
         'IncompleteToolCall',
     ],