# pydantic\_ai.exceptions

### ModelRetry

**Bases:** [`Exception`](https://docs.python.org/3/library/exceptions.html#Exception)

Exception to raise to request a model retry.

Can be raised from tool functions, output validators, and capability hooks (such as `after_model_request`, `after_tool_execute`, etc.) to send a retry prompt back to the model asking it to try again.

#### Attributes

##### message

The message to return to the model.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `message`

#### Methods

##### \_\_get\_pydantic\_core\_schema\_\_

`@classmethod`

```python
def __get_pydantic_core_schema__(cls, _: Any, __: Any) -> core_schema.CoreSchema
```

Pydantic core schema to allow `ModelRetry` to be (de)serialized.

###### Returns

`core_schema.CoreSchema`

### 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](/docs/ai/tools-toolsets/deferred-tools#deferred-tools) for more information.

#### Constructor Parameters

**`metadata`** : [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `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`.

### 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](/docs/ai/tools-toolsets/deferred-tools#human-in-the-loop-tool-approval) for more information.

#### Constructor Parameters

**`metadata`** : [`dict`](https://docs.python.org/3/reference/expressions.html#dict)\[[`str`](https://docs.python.org/3/library/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\] | [`None`](https://docs.python.org/3/library/constants.html#None) _Default:_ `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`.

### SkipModelRequest

**Bases:** [`Exception`](https://docs.python.org/3/library/exceptions.html#Exception)

Exception to raise in before/wrap model request hooks to skip the model call.

The provided response will be used instead of calling the model.

Note: when raised in `before_model_request`, any message history modifications made by earlier capabilities in that hook will not be persisted to the agent's message history, since the request preparation is aborted.

### SkipToolValidation

**Bases:** [`Exception`](https://docs.python.org/3/library/exceptions.html#Exception)

Exception to raise in before/wrap tool validate hooks to skip validation.

The provided args will be used as the validated arguments.

### SkipToolExecution

**Bases:** [`Exception`](https://docs.python.org/3/library/exceptions.html#Exception)

Exception to raise in before/wrap tool execute hooks to skip execution.

The provided result will be used as the tool result.

### UserError

**Bases:** [`RuntimeError`](https://docs.python.org/3/library/exceptions.html#RuntimeError)

Error caused by a usage mistake by the application developer -- You!

#### Attributes

##### message

Description of the mistake.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `message`

### UndrainedPendingMessagesError

**Bases:** [`UserError`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.UserError)

Error raised when an agent run ends with messages still queued via `enqueue`.

A bare `async for node in agent_run` loop only drains `'asap'` messages (in `before_model_request`); `'when_idle'` messages and end-of-run redirects drain in `after_node_run`, which bare iteration skips. Reaching the run's `End` with a non-empty queue means those messages were stranded -- drive the run with `agent.run()` or `AgentRun.next()` instead.

### AgentRunError

**Bases:** [`RuntimeError`](https://docs.python.org/3/library/exceptions.html#RuntimeError)

Base class for errors occurring during an agent run.

#### Attributes

##### message

The error message.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `message`

### UsageLimitExceeded

**Bases:** [`AgentRunError`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.AgentRunError)

Error raised when a Model's usage exceeds the specified limits.

### ConcurrencyLimitExceeded

**Bases:** [`AgentRunError`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.AgentRunError)

Error raised when the concurrency queue depth exceeds max\_queued.

### UnexpectedModelBehavior

**Bases:** [`AgentRunError`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.AgentRunError)

Error caused by unexpected Model behavior, e.g. an unexpected response code.

#### Attributes

##### message

Description of the unexpected behavior.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `message`

##### body

The body of the response, if available.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `json.dumps(json.loads(body), indent=2)`

### ContentFilterError

**Bases:** [`UnexpectedModelBehavior`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior)

Raised when content filtering is triggered by the model provider resulting in an empty response.

### ModelAPIError

**Bases:** [`AgentRunError`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.AgentRunError)

Raised when a model provider API request fails.

#### Attributes

##### model\_name

The name of the model associated with the error.

**Type:** [`str`](https://docs.python.org/3/library/stdtypes.html#str) **Default:** `model_name`

### ModelHTTPError

**Bases:** [`ModelAPIError`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.ModelAPIError)

Raised when a model provider response has a status code of 4xx or 5xx.

#### Attributes

##### status\_code

The HTTP status code returned by the API.

**Type:** [`int`](https://docs.python.org/3/library/functions.html#int) **Default:** `status_code`

##### body

The body of the response, if available.

**Type:** [`object`](https://docs.python.org/3/glossary.html#term-object) | [`None`](https://docs.python.org/3/library/constants.html#None) **Default:** `body`

### FallbackExceptionGroup

**Bases:** `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.

### IncompleteToolCall

**Bases:** [`UnexpectedModelBehavior`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.UnexpectedModelBehavior)

Error raised when a model stops due to token limit while emitting a tool call.