[ Skip to content ](https://ai.pydantic.dev/api/exceptions/#pydantic_aiexceptions)
**Join us at the inaugural PyAI Conf in San Francisco on March 10th![Learn More](https://pyai.events/?utm_source=pydantic-ai) **
[ ![logo](https://ai.pydantic.dev/img/logo-white.svg) ](https://ai.pydantic.dev/ "Pydantic AI")
Pydantic AI
pydantic_ai.exceptions
Type to start searching
[ pydantic/pydantic-ai
  * v1.63.0
  * 15.1k
  * 1.7k

](https://github.com/pydantic/pydantic-ai "Go to repository")
[ ![logo](https://ai.pydantic.dev/img/logo-white.svg) ](https://ai.pydantic.dev/ "Pydantic AI") Pydantic AI
[ pydantic/pydantic-ai
  * v1.63.0
  * 15.1k
  * 1.7k

](https://github.com/pydantic/pydantic-ai "Go to repository")
  * [ Pydantic AI  ](https://ai.pydantic.dev/)
  * [ Installation  ](https://ai.pydantic.dev/install/)
  * [ Getting Help  ](https://ai.pydantic.dev/help/)
  * [ Troubleshooting  ](https://ai.pydantic.dev/troubleshooting/)
  * [ Pydantic AI Gateway  ](https://ai.pydantic.dev/gateway/)
  * Documentation
    * Core Concepts
      * [ Agents  ](https://ai.pydantic.dev/agent/)
      * [ Dependencies  ](https://ai.pydantic.dev/dependencies/)
      * [ Function Tools  ](https://ai.pydantic.dev/tools/)
      * [ Output  ](https://ai.pydantic.dev/output/)
      * [ Messages and chat history  ](https://ai.pydantic.dev/message-history/)
      * [ Direct Model Requests  ](https://ai.pydantic.dev/direct/)
    * Models & Providers
      * [ Overview  ](https://ai.pydantic.dev/models/overview/)
      * [ OpenAI  ](https://ai.pydantic.dev/models/openai/)
      * [ Anthropic  ](https://ai.pydantic.dev/models/anthropic/)
      * [ Google  ](https://ai.pydantic.dev/models/google/)
      * [ xAI  ](https://ai.pydantic.dev/models/xai/)
      * [ Bedrock  ](https://ai.pydantic.dev/models/bedrock/)
      * [ Cerebras  ](https://ai.pydantic.dev/models/cerebras/)
      * [ Cohere  ](https://ai.pydantic.dev/models/cohere/)
      * [ Groq  ](https://ai.pydantic.dev/models/groq/)
      * [ Hugging Face  ](https://ai.pydantic.dev/models/huggingface/)
      * [ Mistral  ](https://ai.pydantic.dev/models/mistral/)
      * [ OpenRouter  ](https://ai.pydantic.dev/models/openrouter/)
      * [ Outlines  ](https://ai.pydantic.dev/models/outlines/)
    * Tools & Toolsets
      * [ Function Tools  ](https://ai.pydantic.dev/tools/)
      * [ Advanced Tool Features  ](https://ai.pydantic.dev/tools-advanced/)
      * [ Toolsets  ](https://ai.pydantic.dev/toolsets/)
      * [ Deferred Tools  ](https://ai.pydantic.dev/deferred-tools/)
      * [ Built-in Tools  ](https://ai.pydantic.dev/builtin-tools/)
      * [ Common Tools  ](https://ai.pydantic.dev/common-tools/)
      * [ Third-Party Tools  ](https://ai.pydantic.dev/third-party-tools/)
    * Advanced Features
      * [ Image, Audio, Video & Document Input  ](https://ai.pydantic.dev/input/)
      * [ Thinking  ](https://ai.pydantic.dev/thinking/)
      * [ HTTP Request Retries  ](https://ai.pydantic.dev/retries/)
    * MCP
      * [ Overview  ](https://ai.pydantic.dev/mcp/overview/)
      * [ Client  ](https://ai.pydantic.dev/mcp/client/)
      * [ FastMCP Client  ](https://ai.pydantic.dev/mcp/fastmcp-client/)
      * [ Server  ](https://ai.pydantic.dev/mcp/server/)
    * [ Multi-Agent Patterns  ](https://ai.pydantic.dev/multi-agent-applications/)
    * [ Web Chat UI  ](https://ai.pydantic.dev/web/)
    * [ Embeddings  ](https://ai.pydantic.dev/embeddings/)
    * [ Testing  ](https://ai.pydantic.dev/testing/)
  * Pydantic Evals
    * [ Overview  ](https://ai.pydantic.dev/evals/)
    * Getting Started
      * [ Quick Start  ](https://ai.pydantic.dev/evals/quick-start/)
      * [ Core Concepts  ](https://ai.pydantic.dev/evals/core-concepts/)
    * Evaluators
      * [ Overview  ](https://ai.pydantic.dev/evals/evaluators/overview/)
      * [ Built-in Evaluators  ](https://ai.pydantic.dev/evals/evaluators/built-in/)
      * [ LLM Judge  ](https://ai.pydantic.dev/evals/evaluators/llm-judge/)
      * [ Custom Evaluators  ](https://ai.pydantic.dev/evals/evaluators/custom/)
      * [ Report Evaluators  ](https://ai.pydantic.dev/evals/evaluators/report-evaluators/)
      * [ Span-Based  ](https://ai.pydantic.dev/evals/evaluators/span-based/)
    * How-To Guides
      * [ Logfire Integration  ](https://ai.pydantic.dev/evals/how-to/logfire-integration/)
      * [ Dataset Management  ](https://ai.pydantic.dev/evals/how-to/dataset-management/)
      * [ Dataset Serialization  ](https://ai.pydantic.dev/evals/how-to/dataset-serialization/)
      * [ Concurrency & Performance  ](https://ai.pydantic.dev/evals/how-to/concurrency/)
      * [ Multi-Run Evaluation  ](https://ai.pydantic.dev/evals/how-to/multi-run/)
      * [ Retry Strategies  ](https://ai.pydantic.dev/evals/how-to/retry-strategies/)
      * [ Metrics & Attributes  ](https://ai.pydantic.dev/evals/how-to/metrics-attributes/)
    * Examples
      * [ Simple Validation  ](https://ai.pydantic.dev/evals/examples/simple-validation/)
  * Pydantic Graph
    * [ Overview  ](https://ai.pydantic.dev/graph/)
    * [ Beta API  ](https://ai.pydantic.dev/graph/beta/)
      * [ Steps  ](https://ai.pydantic.dev/graph/beta/steps/)
      * [ Joins & Reducers  ](https://ai.pydantic.dev/graph/beta/joins/)
      * [ Decisions  ](https://ai.pydantic.dev/graph/beta/decisions/)
      * [ Parallel Execution  ](https://ai.pydantic.dev/graph/beta/parallel/)
  * Integrations
    * [ Debugging & Monitoring with Pydantic Logfire  ](https://ai.pydantic.dev/logfire/)
    * Durable Execution
      * [ Overview  ](https://ai.pydantic.dev/durable_execution/overview/)
      * [ Temporal  ](https://ai.pydantic.dev/durable_execution/temporal/)
      * [ DBOS  ](https://ai.pydantic.dev/durable_execution/dbos/)
      * [ Prefect  ](https://ai.pydantic.dev/durable_execution/prefect/)
    * UI Event Streams
      * [ Overview  ](https://ai.pydantic.dev/ui/overview/)
      * [ AG-UI  ](https://ai.pydantic.dev/ui/ag-ui/)
      * [ Vercel AI  ](https://ai.pydantic.dev/ui/vercel-ai/)
    * [ Agent2Agent (A2A)  ](https://ai.pydantic.dev/a2a/)
  * Related Packages
    * [ clai  ](https://ai.pydantic.dev/cli/)
  * Examples
    * [ Setup  ](https://ai.pydantic.dev/examples/setup/)
    * Getting Started
      * [ Pydantic Model  ](https://ai.pydantic.dev/examples/pydantic-model/)
      * [ Weather agent  ](https://ai.pydantic.dev/examples/weather-agent/)
    * Conversational Agents
      * [ Chat App with FastAPI  ](https://ai.pydantic.dev/examples/chat-app/)
      * [ Bank support  ](https://ai.pydantic.dev/examples/bank-support/)
    * Data & Analytics
      * [ SQL Generation  ](https://ai.pydantic.dev/examples/sql-gen/)
      * [ Data Analyst  ](https://ai.pydantic.dev/examples/data-analyst/)
      * [ RAG  ](https://ai.pydantic.dev/examples/rag/)
    * Streaming
      * [ Stream markdown  ](https://ai.pydantic.dev/examples/stream-markdown/)
      * [ Stream whales  ](https://ai.pydantic.dev/examples/stream-whales/)
    * Complex Workflows
      * [ Flight booking  ](https://ai.pydantic.dev/examples/flight-booking/)
      * [ Question Graph  ](https://ai.pydantic.dev/examples/question-graph/)
    * Business Applications
      * [ Slack Lead Qualifier with Modal  ](https://ai.pydantic.dev/examples/slack-lead-qualifier/)
    * UI Examples
      * [ Agent User Interaction (AG-UI)  ](https://ai.pydantic.dev/examples/ag-ui/)
  * API Reference
    * pydantic_ai
      * [ pydantic_ai.ag_ui  ](https://ai.pydantic.dev/api/ag_ui/)
      * [ pydantic_ai.agent  ](https://ai.pydantic.dev/api/agent/)
      * [ pydantic_ai.builtin_tools  ](https://ai.pydantic.dev/api/builtin_tools/)
      * [ pydantic_ai.common_tools  ](https://ai.pydantic.dev/api/common_tools/)
      * [ pydantic_ai — Concurrency  ](https://ai.pydantic.dev/api/concurrency/)
      * [ pydantic_ai.direct  ](https://ai.pydantic.dev/api/direct/)
      * [ pydantic_ai.durable_exec  ](https://ai.pydantic.dev/api/durable_exec/)
      * [ pydantic_ai.embeddings  ](https://ai.pydantic.dev/api/embeddings/)
      * pydantic_ai.exceptions  [ pydantic_ai.exceptions  ](https://ai.pydantic.dev/api/exceptions/)
        * [ exceptions  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions)
        * [ ModelRetry  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry)
          * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry.message)
          * [ __get_pydantic_core_schema__  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry.__get_pydantic_core_schema__)
        * [ CallDeferred  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.CallDeferred)
        * [ ApprovalRequired  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ApprovalRequired)
        * [ UserError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UserError)
          * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UserError.message)
        * [ AgentRunError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError)
          * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError.message)
        * [ UsageLimitExceeded  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UsageLimitExceeded)
        * [ ConcurrencyLimitExceeded  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ConcurrencyLimitExceeded)
        * [ UnexpectedModelBehavior  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior)
          * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior.message)
          * [ body  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior.body)
        * [ ContentFilterError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ContentFilterError)
        * [ ModelAPIError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelAPIError)
          * [ model_name  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelAPIError.model_name)
        * [ ModelHTTPError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelHTTPError)
          * [ status_code  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelHTTPError.status_code)
          * [ body  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelHTTPError.body)
        * [ FallbackExceptionGroup  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.FallbackExceptionGroup)
        * [ ToolRetryError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ToolRetryError)
        * [ IncompleteToolCall  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.IncompleteToolCall)
      * [ pydantic_ai.ext  ](https://ai.pydantic.dev/api/ext/)
      * [ pydantic_ai.format_prompt  ](https://ai.pydantic.dev/api/format_prompt/)
      * [ pydantic_ai.mcp  ](https://ai.pydantic.dev/api/mcp/)
      * [ pydantic_ai.messages  ](https://ai.pydantic.dev/api/messages/)
      * [ pydantic_ai.models.anthropic  ](https://ai.pydantic.dev/api/models/anthropic/)
      * [ pydantic_ai.models  ](https://ai.pydantic.dev/api/models/base/)
      * [ pydantic_ai.models.bedrock  ](https://ai.pydantic.dev/api/models/bedrock/)
      * [ pydantic_ai.models.cerebras  ](https://ai.pydantic.dev/api/models/cerebras/)
      * [ pydantic_ai.models.cohere  ](https://ai.pydantic.dev/api/models/cohere/)
      * [ pydantic_ai.models.fallback  ](https://ai.pydantic.dev/api/models/fallback/)
      * [ pydantic_ai.models.function  ](https://ai.pydantic.dev/api/models/function/)
      * [ pydantic_ai.models.google  ](https://ai.pydantic.dev/api/models/google/)
      * [ pydantic_ai.models.xai  ](https://ai.pydantic.dev/api/models/xai/)
      * [ pydantic_ai.models.groq  ](https://ai.pydantic.dev/api/models/groq/)
      * [ pydantic_ai.models.huggingface  ](https://ai.pydantic.dev/api/models/huggingface/)
      * [ pydantic_ai.models.instrumented  ](https://ai.pydantic.dev/api/models/instrumented/)
      * [ pydantic_ai.models.mcp_sampling  ](https://ai.pydantic.dev/api/models/mcp-sampling/)
      * [ pydantic_ai.models.mistral  ](https://ai.pydantic.dev/api/models/mistral/)
      * [ pydantic_ai.models.openai  ](https://ai.pydantic.dev/api/models/openai/)
      * [ pydantic_ai.models.openrouter  ](https://ai.pydantic.dev/api/models/openrouter/)
      * [ pydantic_ai.models.outlines  ](https://ai.pydantic.dev/api/models/outlines/)
      * [ pydantic_ai.models.test  ](https://ai.pydantic.dev/api/models/test/)
      * [ pydantic_ai.models.wrapper  ](https://ai.pydantic.dev/api/models/wrapper/)
      * [ pydantic_ai.output  ](https://ai.pydantic.dev/api/output/)
      * [ pydantic_ai.profiles  ](https://ai.pydantic.dev/api/profiles/)
      * [ pydantic_ai.providers  ](https://ai.pydantic.dev/api/providers/)
      * [ pydantic_ai.result  ](https://ai.pydantic.dev/api/result/)
      * [ pydantic_ai.retries  ](https://ai.pydantic.dev/api/retries/)
      * [ pydantic_ai.run  ](https://ai.pydantic.dev/api/run/)
      * [ pydantic_ai.settings  ](https://ai.pydantic.dev/api/settings/)
      * [ pydantic_ai.tools  ](https://ai.pydantic.dev/api/tools/)
      * [ pydantic_ai.toolsets  ](https://ai.pydantic.dev/api/toolsets/)
      * [ pydantic_ai.ui.ag_ui  ](https://ai.pydantic.dev/api/ui/ag_ui/)
      * [ pydantic_ai.ui  ](https://ai.pydantic.dev/api/ui/base/)
      * [ pydantic_ai.ui.vercel_ai  ](https://ai.pydantic.dev/api/ui/vercel_ai/)
      * [ pydantic_ai.usage  ](https://ai.pydantic.dev/api/usage/)
    * pydantic_evals
      * [ pydantic_evals.dataset  ](https://ai.pydantic.dev/api/pydantic_evals/dataset/)
      * [ pydantic_evals.evaluators  ](https://ai.pydantic.dev/api/pydantic_evals/evaluators/)
      * [ pydantic_evals.reporting  ](https://ai.pydantic.dev/api/pydantic_evals/reporting/)
      * [ pydantic_evals.otel  ](https://ai.pydantic.dev/api/pydantic_evals/otel/)
      * [ pydantic_evals.generation  ](https://ai.pydantic.dev/api/pydantic_evals/generation/)
    * pydantic_graph
      * [ pydantic_graph  ](https://ai.pydantic.dev/api/pydantic_graph/graph/)
      * [ pydantic_graph.nodes  ](https://ai.pydantic.dev/api/pydantic_graph/nodes/)
      * [ pydantic_graph.persistence  ](https://ai.pydantic.dev/api/pydantic_graph/persistence/)
      * [ pydantic_graph.mermaid  ](https://ai.pydantic.dev/api/pydantic_graph/mermaid/)
      * [ pydantic_graph.exceptions  ](https://ai.pydantic.dev/api/pydantic_graph/exceptions/)
      * Beta API
        * [ pydantic_graph.beta  ](https://ai.pydantic.dev/api/pydantic_graph/beta/)
        * [ pydantic_graph.beta.graph  ](https://ai.pydantic.dev/api/pydantic_graph/beta_graph/)
        * [ pydantic_graph.beta.graph_builder  ](https://ai.pydantic.dev/api/pydantic_graph/beta_graph_builder/)
        * [ pydantic_graph.beta.step  ](https://ai.pydantic.dev/api/pydantic_graph/beta_step/)
        * [ pydantic_graph.beta.join  ](https://ai.pydantic.dev/api/pydantic_graph/beta_join/)
        * [ pydantic_graph.beta.decision  ](https://ai.pydantic.dev/api/pydantic_graph/beta_decision/)
        * [ pydantic_graph.beta.node  ](https://ai.pydantic.dev/api/pydantic_graph/beta_node/)
    * fasta2a
      * [ fasta2a  ](https://ai.pydantic.dev/api/fasta2a/)
  * Project
    * [ Contributing  ](https://ai.pydantic.dev/contributing/)
    * [ Upgrade Guide  ](https://ai.pydantic.dev/changelog/)
    * [ Version policy  ](https://ai.pydantic.dev/version-policy/)


  * [ exceptions  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions)
  * [ ModelRetry  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry)
    * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry.message)
    * [ __get_pydantic_core_schema__  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelRetry.__get_pydantic_core_schema__)
  * [ CallDeferred  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.CallDeferred)
  * [ ApprovalRequired  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ApprovalRequired)
  * [ UserError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UserError)
    * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UserError.message)
  * [ AgentRunError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError)
    * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError.message)
  * [ UsageLimitExceeded  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UsageLimitExceeded)
  * [ ConcurrencyLimitExceeded  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ConcurrencyLimitExceeded)
  * [ UnexpectedModelBehavior  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior)
    * [ message  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior.message)
    * [ body  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior.body)
  * [ ContentFilterError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ContentFilterError)
  * [ ModelAPIError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelAPIError)
    * [ model_name  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelAPIError.model_name)
  * [ ModelHTTPError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelHTTPError)
    * [ status_code  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelHTTPError.status_code)
    * [ body  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelHTTPError.body)
  * [ FallbackExceptionGroup  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.FallbackExceptionGroup)
  * [ ToolRetryError  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ToolRetryError)
  * [ IncompleteToolCall  ](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.IncompleteToolCall)


  1. [ Pydantic AI  ](https://ai.pydantic.dev/)
  2. [ API Reference  ](https://ai.pydantic.dev/api/ag_ui/)
  3. [ pydantic_ai  ](https://ai.pydantic.dev/api/ag_ui/)


# `pydantic_ai.exceptions`
###  ModelRetry
Bases: `Exception[](https://docs.python.org/3/library/exceptions.html#Exception)`
Exception to raise when a tool function should be retried.
The agent will return the message to the model and ask it to try calling the function/tool again.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
```
| ```
class ModelRetry(Exception):
    """Exception to raise when a tool function should be retried.

    The agent will return the message to the model and ask it to try calling the function/tool again.
    """

    message: str
    """The message to return to the model."""

    def __init__(self, message: str):
        self.message = message
        super().__init__(message)

    def __eq__(self, other: Any) -> bool:
        return isinstance(other, self.__class__) and other.message == self.message

    def __hash__(self) -> int:
        return hash((self.__class__, self.message))

    @classmethod
    def __get_pydantic_core_schema__(cls, _: Any, __: Any) -> core_schema.CoreSchema:
        """Pydantic core schema to allow `ModelRetry` to be (de)serialized."""
        schema = core_schema.typed_dict_schema(
            {
                'message': core_schema.typed_dict_field(core_schema.str_schema()),
                'kind': core_schema.typed_dict_field(core_schema.literal_schema(['model-retry'])),
            }
        )
        return core_schema.no_info_after_validator_function(
            lambda dct: ModelRetry(dct['message']),
            schema,
            serialization=core_schema.plain_serializer_function_ser_schema(
                lambda x: {'message': x.message, 'kind': 'model-retry'},
                return_schema=schema,
            ),
        )

```

---|---
####  message `instance-attribute`
```
message: str[](https://docs.python.org/3/library/stdtypes.html#str) = message

```

The message to return to the model.
####  __get_pydantic_core_schema__ `classmethod`
```
__get_pydantic_core_schema__(_: Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any"), __: Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")) -> CoreSchema

```

Pydantic core schema to allow `ModelRetry` to be (de)serialized.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
```
| ```
@classmethod
def __get_pydantic_core_schema__(cls, _: Any, __: Any) -> core_schema.CoreSchema:
    """Pydantic core schema to allow `ModelRetry` to be (de)serialized."""
    schema = core_schema.typed_dict_schema(
        {
            'message': core_schema.typed_dict_field(core_schema.str_schema()),
            'kind': core_schema.typed_dict_field(core_schema.literal_schema(['model-retry'])),
        }
    )
    return core_schema.no_info_after_validator_function(
        lambda dct: ModelRetry(dct['message']),
        schema,
        serialization=core_schema.plain_serializer_function_ser_schema(
            lambda x: {'message': x.message, 'kind': 'model-retry'},
            return_schema=schema,
        ),
    )

```

---|---
###  CallDeferred
Bases: `Exception[](https://docs.python.org/3/library/exceptions.html#Exception)`
Exception to raise when a tool call should be deferred.
See [tools docs](https://ai.pydantic.dev/deferred-tools/#deferred-tools) for more information.
Parameters:
Name | Type | Description | Default
---|---|---|---
`metadata` |  `dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] | None` |  Optional dictionary of metadata to attach to the deferred tool call. This metadata will be available in `DeferredToolRequests.metadata` keyed by `tool_call_id`. |  `None`
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
74
75
76
77
78
79
80
81
82
83
84
85
86
```
| ```
class CallDeferred(Exception):
    """Exception to raise when a tool call should be deferred.

    See [tools docs](../deferred-tools.md#deferred-tools) for more information.

    Args:
        metadata: Optional dictionary of metadata to attach to the deferred tool call.
            This metadata will be available in `DeferredToolRequests.metadata` keyed by `tool_call_id`.
    """

    def __init__(self, metadata: dict[str, Any] | None = None):
        self.metadata = metadata
        super().__init__()

```

---|---
###  ApprovalRequired
Bases: `Exception[](https://docs.python.org/3/library/exceptions.html#Exception)`
Exception to raise when a tool call requires human-in-the-loop approval.
See [tools docs](https://ai.pydantic.dev/deferred-tools/#human-in-the-loop-tool-approval) for more information.
Parameters:
Name | Type | Description | Default
---|---|---|---
`metadata` |  `dict[](https://docs.python.org/3/library/stdtypes.html#dict)[str[](https://docs.python.org/3/library/stdtypes.html#str), Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")] | None` |  Optional dictionary of metadata to attach to the deferred tool call. This metadata will be available in `DeferredToolRequests.metadata` keyed by `tool_call_id`. |  `None`
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
```
| ```
class ApprovalRequired(Exception):
    """Exception to raise when a tool call requires human-in-the-loop approval.

    See [tools docs](../deferred-tools.md#human-in-the-loop-tool-approval) for more information.

    Args:
        metadata: Optional dictionary of metadata to attach to the deferred tool call.
            This metadata will be available in `DeferredToolRequests.metadata` keyed by `tool_call_id`.
    """

    def __init__(self, metadata: dict[str, Any] | None = None):
        self.metadata = metadata
        super().__init__()

```

---|---
###  UserError
Bases: `RuntimeError[](https://docs.python.org/3/library/exceptions.html#RuntimeError)`
Error caused by a usage mistake by the application developer — You!
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
104
105
106
107
108
109
110
111
112
```
| ```
class UserError(RuntimeError):
    """Error caused by a usage mistake by the application developer — You!"""

    message: str
    """Description of the mistake."""

    def __init__(self, message: str):
        self.message = message
        super().__init__(message)

```

---|---
####  message `instance-attribute`
```
message: str[](https://docs.python.org/3/library/stdtypes.html#str) = message

```

Description of the mistake.
###  AgentRunError
Bases: `RuntimeError[](https://docs.python.org/3/library/exceptions.html#RuntimeError)`
Base class for errors occurring during an agent run.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
115
116
117
118
119
120
121
122
123
124
125
126
```
| ```
class AgentRunError(RuntimeError):
    """Base class for errors occurring during an agent run."""

    message: str
    """The error message."""

    def __init__(self, message: str):
        self.message = message
        super().__init__(message)

    def __str__(self) -> str:
        return self.message

```

---|---
####  message `instance-attribute`
```
message: str[](https://docs.python.org/3/library/stdtypes.html#str) = message

```

The error message.
###  UsageLimitExceeded
Bases: `AgentRunError[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError "AgentRunError \(pydantic_ai.exceptions.AgentRunError\)")`
Error raised when a Model's usage exceeds the specified limits.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
129
130
```
| ```
class UsageLimitExceeded(AgentRunError):
    """Error raised when a Model's usage exceeds the specified limits."""

```

---|---
###  ConcurrencyLimitExceeded
Bases: `AgentRunError[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError "AgentRunError \(pydantic_ai.exceptions.AgentRunError\)")`
Error raised when the concurrency queue depth exceeds max_queued.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
133
134
```
| ```
class ConcurrencyLimitExceeded(AgentRunError):
    """Error raised when the concurrency queue depth exceeds max_queued."""

```

---|---
###  UnexpectedModelBehavior
Bases: `AgentRunError[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError "AgentRunError \(pydantic_ai.exceptions.AgentRunError\)")`
Error caused by unexpected Model behavior, e.g. an unexpected response code.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
```
| ```
class UnexpectedModelBehavior(AgentRunError):
    """Error caused by unexpected Model behavior, e.g. an unexpected response code."""

    message: str
    """Description of the unexpected behavior."""
    body: str | None
    """The body of the response, if available."""

    def __init__(self, message: str, body: str | None = None):
        self.message = message
        if body is None:
            self.body: str | None = None
        else:
            try:
                self.body = json.dumps(json.loads(body), indent=2)
            except ValueError:
                self.body = body
        super().__init__(message)

    def __str__(self) -> str:
        if self.body:
            return f'{self.message}, body:\n{self.body}'
        else:
            return self.message

```

---|---
####  message `instance-attribute`
```
message: str[](https://docs.python.org/3/library/stdtypes.html#str) = message

```

Description of the unexpected behavior.
####  body `instance-attribute`
```
body: str[](https://docs.python.org/3/library/stdtypes.html#str) | None = dumps[](https://docs.python.org/3/library/json.html#json.dumps "json.dumps")(loads[](https://docs.python.org/3/library/json.html#json.loads "json.loads")(body), indent=2)

```

The body of the response, if available.
###  ContentFilterError
Bases: `UnexpectedModelBehavior[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior "UnexpectedModelBehavior \(pydantic_ai.exceptions.UnexpectedModelBehavior\)")`
Raised when content filtering is triggered by the model provider resulting in an empty response.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
163
164
```
| ```
class ContentFilterError(UnexpectedModelBehavior):
    """Raised when content filtering is triggered by the model provider resulting in an empty response."""

```

---|---
###  ModelAPIError
Bases: `AgentRunError[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.AgentRunError "AgentRunError \(pydantic_ai.exceptions.AgentRunError\)")`
Raised when a model provider API request fails.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
167
168
169
170
171
172
173
174
175
```
| ```
class ModelAPIError(AgentRunError):
    """Raised when a model provider API request fails."""

    model_name: str
    """The name of the model associated with the error."""

    def __init__(self, model_name: str, message: str):
        self.model_name = model_name
        super().__init__(message)

```

---|---
####  model_name `instance-attribute`
```
model_name: str[](https://docs.python.org/3/library/stdtypes.html#str) = model_name

```

The name of the model associated with the error.
###  ModelHTTPError
Bases: `ModelAPIError[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.ModelAPIError "ModelAPIError \(pydantic_ai.exceptions.ModelAPIError\)")`
Raised when an model provider response has a status code of 4xx or 5xx.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
178
179
180
181
182
183
184
185
186
187
188
189
190
191
```
| ```
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."""

    body: object | None
    """The body of the response, if available."""

    def __init__(self, status_code: int, model_name: str, body: object | None = None):
        self.status_code = status_code
        self.body = body
        message = f'status_code: {status_code}, model_name: {model_name}, body: {body}'
        super().__init__(model_name=model_name, message=message)

```

---|---
####  status_code `instance-attribute`
```
status_code: int[](https://docs.python.org/3/library/functions.html#int) = status_code

```

The HTTP status code returned by the API.
####  body `instance-attribute`
```
body: object[](https://docs.python.org/3/library/functions.html#object) | None = body

```

The body of the response, if available.
###  FallbackExceptionGroup
Bases: `ExceptionGroup[Any[](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]`
A group of exceptions that can be raised when all fallback models fail.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
194
195
```
| ```
class FallbackExceptionGroup(ExceptionGroup[Any]):
    """A group of exceptions that can be raised when all fallback models fail."""

```

---|---
###  ToolRetryError
Bases: `Exception[](https://docs.python.org/3/library/exceptions.html#Exception)`
Exception used to signal a `ToolRetry` message should be returned to the LLM.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
```
| ```
class ToolRetryError(Exception):
    """Exception used to signal a `ToolRetry` message should be returned to the LLM."""

    def __init__(self, tool_retry: RetryPromptPart):
        self.tool_retry = tool_retry
        message = (
            tool_retry.content
            if isinstance(tool_retry.content, str)
            else self._format_error_details(tool_retry.content, tool_retry.tool_name)
        )
        super().__init__(message)

    @staticmethod
    def _format_error_details(errors: list[pydantic_core.ErrorDetails], tool_name: str | None) -> str:
        """Format ErrorDetails as a human-readable message.

        We format manually rather than using ValidationError.from_exception_data because
        some error types (value_error, assertion_error, etc.) require an 'error' key in ctx,
        but when ErrorDetails are serialized, exception objects are stripped from ctx.
        The 'msg' field already contains the human-readable message, so we use that directly.
        """
        error_count = len(errors)
        lines = [
            f'{error_count} validation error{"" if error_count == 1 else "s"}{f" for {tool_name!r}" if tool_name else ""}'
        ]
        for e in errors:
            loc = '.'.join(str(x) for x in e['loc']) if e['loc'] else '__root__'
            lines.append(loc)
            lines.append(f'  {e["msg"]} [type={e["type"]}, input_value={e["input"]!r}]')
        return '\n'.join(lines)

```

---|---
###  IncompleteToolCall
Bases: `UnexpectedModelBehavior[](https://ai.pydantic.dev/api/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior "UnexpectedModelBehavior \(pydantic_ai.exceptions.UnexpectedModelBehavior\)")`
Error raised when a model stops due to token limit while emitting a tool call.
Source code in `pydantic_ai_slim/pydantic_ai/exceptions.py`
```
230
231
```
| ```
class IncompleteToolCall(UnexpectedModelBehavior):
    """Error raised when a model stops due to token limit while emitting a tool call."""

```

---|---
© Pydantic Services Inc. 2024 to present
