> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# errors • AI Agent SDK

> Structured exception hierarchy for PraisonAI SDK.

# errors

<Badge color="blue">AI Agent</Badge>

Structured exception hierarchy for PraisonAI SDK.

Provides uniform error semantics for consistent handling across:

* Multi-agent orchestration
* Tool execution
* LLM interactions
* Memory operations
* External integrations

## Import

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import errors
```

## Classes

<CardGroup cols={2}>
  <Card title="FailoverDecision" icon="brackets-curly" href="../classes/FailoverDecision">
    Discriminated struct for retry and failover decisions.
  </Card>

  <Card title="IdleTimeoutBreaker" icon="brackets-curly" href="../classes/IdleTimeoutBreaker">
    Circuit breaker for consecutive idle-timeout failures.
  </Card>

  <Card title="ErrorContextProtocol" icon="brackets-curly" href="../classes/ErrorContextProtocol">
    Protocol for structured error context propagation.
  </Card>

  <Card title="PraisonAIError" icon="brackets-curly" href="../classes/PraisonAIError">
    Base error class with structured context for PraisonAI SDK.
  </Card>

  <Card title="ToolExecutionError" icon="brackets-curly" href="../classes/ToolExecutionError">
    Tool execution failed.
  </Card>

  <Card title="LLMError" icon="brackets-curly" href="../classes/LLMError">
    LLM interaction failed.
  </Card>

  <Card title="BudgetExceededError" icon="brackets-curly" href="../classes/BudgetExceededError">
    Budget limits exceeded (tokens, time, etc).
  </Card>

  <Card title="ValidationError" icon="brackets-curly" href="../classes/ValidationError">
    Input validation failed.
  </Card>

  <Card title="NetworkError" icon="brackets-curly" href="../classes/NetworkError">
    Network/external service error.
  </Card>

  <Card title="HandoffError" icon="brackets-curly" href="../classes/HandoffError">
    Agent handoff/delegation failed.
  </Card>

  <Card title="PraisonAIConfigError" icon="brackets-curly" href="../classes/PraisonAIConfigError">
    Configuration error (missing API keys, invalid settings, etc).
  </Card>

  <Card title="HandoffCycleError" icon="brackets-curly" href="../classes/HandoffCycleError">
    Circular handoff dependency detected.
  </Card>

  <Card title="HandoffDepthError" icon="brackets-curly" href="../classes/HandoffDepthError">
    Maximum handoff depth exceeded.
  </Card>

  <Card title="HandoffTimeoutError" icon="brackets-curly" href="../classes/HandoffTimeoutError">
    Handoff operation timed out.
  </Card>

  <Card title="HandoffValidationError" icon="brackets-curly" href="../classes/HandoffValidationError">
    Raised when a typed handoff payload does not satisfy the declared schema.
  </Card>
</CardGroup>

### Constants

| Name                        | Value                                                                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `LEGACY_ERROR_CATEGORY_MAP` | `{'tool': 'unknown', 'llm': 'unknown', 'budget': 'billing', 'validation': 'format_error', 'network': 'unknown', 'handoff': 'unknown'}` |