Error Handling

Definable is designed to fail fast with clear, actionable errors. This page covers the exception types, retry strategies, and patterns for building resilient agents.

Exception Types

Agent Errors

Exception	When It’s Raised
`AgentError`	General agent execution failure
`MaxIterationsError`	Agent exceeded `max_iterations` in the tool-call loop
`ToolExecutionError`	A tool raised an exception during execution

Model Errors

Model errors typically come from the underlying provider SDK (e.g., openai.APIError). Common cases:

Error	Cause	Recommended Action
`AuthenticationError`	Invalid API key	Check your API key
`RateLimitError`	Too many requests	Use retries with backoff
`APIConnectionError`	Network failure	Use retries
`APITimeoutError`	Request timed out	Increase timeout or use retries
`BadRequestError`	Invalid request parameters	Check model parameters

MCP Errors

See MCP Error Handling for the full MCP error hierarchy.

Agent-Level Retries

Configure retries directly on the agent:

from definable.agent import Agent, AgentConfig

agent = Agent(
    model=model,
    config=AgentConfig(
        retry_transient_errors=True,
        max_retries=3,
    ),
)

This retries the entire agent run on transient errors (connection failures, timeouts).

Model-Level Retries

Configure retries on the model itself for finer control:

from definable.model import OpenAIChat

model = OpenAIChat(
    id="gpt-4o",
    retries=3,
    delay_between_retries=2,
    exponential_backoff=True,
)

Model retries apply to individual API calls. Agent retries wrap the entire run.

Retry Middleware

For the most control, use RetryMiddleware:

from definable.agent import Agent, RetryMiddleware

agent = Agent(model=model).use(
    RetryMiddleware(
        max_retries=3,
        backoff_base=1.0,
        backoff_max=60.0,
    )
)

The middleware retries on ConnectionError, TimeoutError, and OSError with exponential backoff.

Tool Error Handling

When a tool raises an exception, the error message is sent back to the model. The model can then decide to retry the call, try a different approach, or inform the user:

from definable.tool.decorator import tool

@tool
def divide(a: float, b: float) -> str:
    """Divide two numbers."""
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return str(a / b)

If the model calls divide(10, 0), it receives the error "Cannot divide by zero" and can adjust its approach.

Catching Errors in Application Code

from definable.agent import Agent

agent = Agent(model=model, tools=[my_tool])

try:
    output = agent.run("Do something risky.")
except Exception as e:
    print(f"Agent failed: {e}")
    # Log, notify, or fall back

Streaming Error Handling

During streaming, errors arrive as RunErrorEvent:

for event in agent.run_stream("Do something."):
    if event.event == "RunError":
        print(f"Error: {event.error}")
        break
    if event.event == "RunContent":
        print(event.content, end="")

Best Practices

Set appropriate timeouts — Don’t let requests hang indefinitely
Use retries for transient errors — Network issues are temporary
Raise clear errors in tools — The model uses error messages to self-correct
Log errors — Use LoggingMiddleware for visibility into failures
Test error paths — Use MockModel with side_effect to simulate failures

Get Started

Basics

Capabilities

Advanced

Exception Types

Agent Errors

Model Errors

MCP Errors

Agent-Level Retries

Model-Level Retries

Retry Middleware

Tool Error Handling

Catching Errors in Application Code

Streaming Error Handling

Best Practices

​Exception Types

​Agent Errors

​Model Errors

​MCP Errors

​Agent-Level Retries

​Model-Level Retries

​Retry Middleware

​Tool Error Handling

​Catching Errors in Application Code

​Streaming Error Handling

​Best Practices

Exception Types

Agent Errors

Model Errors

MCP Errors

Agent-Level Retries

Model-Level Retries

Retry Middleware

Tool Error Handling

Catching Errors in Application Code

Streaming Error Handling

Best Practices