Fallback Models: Error-Specific

Use FallbackConfig for error-specific fallback routing.

The source says on_error handles any error. In the audited main source, fallback routing catches ModelProviderError and uses on_error only for retryable provider failures. Ordinary client errors such as 400, 401, and 403 responses, plus non-provider exceptions, propagate without using this fallback.

error_specific_fallbacks.py
"""
Fallback Models — Error-Specific
==================================

Use FallbackConfig for error-specific fallback routing.

- on_error: tried on any error from the primary model.
- on_rate_limit: tried specifically on rate-limit (429) errors.
- on_context_overflow: tried on context-window-exceeded errors.

When a specific fallback list matches the error type, it takes
priority over the general on_error list.
"""

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.models.fallback import FallbackConfig
from agno.models.openai import OpenAIChat

# ---------------------------------------------------------------------------
# Create Agent with error-specific fallbacks
# ---------------------------------------------------------------------------
agent = Agent(
    model=OpenAIChat(id="gpt-5.6-luna"),
    fallback_config=FallbackConfig(
        # On rate-limit errors, try these models (in order)
        on_rate_limit=[
            OpenAIChat(id="gpt-5.6-luna"),
            Claude(id="claude-sonnet-4-20250514"),
        ],
        # On context-window-exceeded errors, try a model with a larger window
        on_context_overflow=[
            Claude(id="claude-sonnet-4-20250514"),
        ],
        # General fallback for all other errors
        on_error=[
            Claude(id="claude-sonnet-4-20250514"),
        ],
    ),
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response("What is the meaning of life?", stream=True)

Use a current fallback model

Before running, replace every Claude(id="claude-sonnet-4-20250514") with Claude(id="claude-sonnet-4-6"). The original Sonnet 4 API model retired on June 15, 2026; see Claude model deprecations. The source is preserved above, and the setup still requires both providers' API keys.

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno anthropic openai

Export your API keys

export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Run the example

Save the code above as error_specific_fallbacks.py, then run:

python error_specific_fallbacks.py

Full source: cookbook/02_agents/17_fallback_models/02_error_specific_fallbacks.py