Model Fallback

When the primary model is temporarily unavailable (529 overloaded / 429 rate-limited / 5xx / unreachable), the request automatically continues on a fallback model, so a single upstream outage doesn't break your agent run. Compatible with OpenRouter's models parameter.

Pick either way to set it up:

Scenario	How
Clients that can't change request params (Claude Code, Cursor, etc.)	Set a fallback model on your key in the API Keys page — no config change needed
Calling the API from your own code	Add models to the request body

Option 1: set a fallback model on the API Keys page

1. Open the API Keys page.
2. In the row of the key you use, pick a model from the "Fallback model" dropdown. It saves automatically.

From then on, every request sent with this key switches to that model when the primary model is unavailable.

Option 2: send models in the request body

model is still the primary model; models lists the fallbacks in order. If model is omitted, the first entry of models is used as the primary.

curl -X POST "https://router.bumo.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-5-5",
    "models": ["gpt-6-astra", "gemini-3.8-flash"],
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

• The request wins: if the request includes models, it takes precedence over the fallback model set on the key.
• Turn off fallback for one request: send "models": []. Only the primary model is used, and the key's fallback model is ignored.
• Up to 3 models (including the primary); extras are ignored and duplicates are removed.
• models is consumed by the platform and never forwarded to the upstream provider.

When does it switch?

• Only when every route of the primary model has failed with a retriable error (429 / 529 / 5xx / network failure).
• 4xx errors don't trigger fallback (e.g. context too long, malformed body). They are returned as-is, since another model wouldn't fix them.
• No switching once streaming has started: a switch only happens before any output is sent, so you never get half a response from model A and the rest from model B.
• Fallback models that don't exist or aren't available are skipped.
• If every model in the chain fails, the last model's error is returned.

Billing and visibility

• Billed at the model that actually succeeded, using that model's price. No extra fee.
• The model field in the response is the model that actually served the request. When fallback happens, the response carries the header X-Router-Fallback-From: <primary model>, which you can check in code.
• In Wallet → usage records, fallback requests show Fallback from <primary model> under the model name.