Fallback

provider.fallback lists backup models to try, in order, when the primary model fails upstream.

Configuration

fallback takes an array of model IDs and sits alongside type under provider. At most 3 models; more returns 400.

cURL

Terminal


curl https://api.ofox.run/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"]
      }
    }
  }'

Python

fallback.py


client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "extra_body": {
            "provider": {
                "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"],
            }
        }
    },
)

TypeScript

fallback.ts


await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: '...' }],
  extra_body: {
    provider: {
      fallback: ['openai/gpt-5.5', 'google/gemini-2.5-pro'],
    },
  },
} as any)

With the official OpenAI SDKs, extra_body must be present as a literal key in the request body. The TypeScript SDK sends it as written in the params object. The Python SDK’s extra_body= argument merges its contents into the top level of the body, so the key must be nested one level deeper, or passed as a request header instead.

What triggers a fallback

A fallback only covers failures that happen after routing has chosen a channel:

Situation	Behaviour
The upstream provider returns an error	Falls back — the listed models are tried in order, and the first success is returned
Routing itself fails (model does not exist, or the pinned provider does not serve it)	No fallback — the request terminates immediately

The second row is worth stating plainly: pinning provider.type to a provider that does not serve the model returns 400 provider_type_unavailable, and naming a model that does not exist returns 404 model_not_found. Neither one reaches the fallback list. Exactly which upstream errors trigger a fallback follows the gateway’s behaviour rather than a fixed list.

Combining with a pinned provider

fallback and type can be sent together — type constrains where the primary model runs, fallback covers what happens if it fails:


{
  "model": "anthropic/claude-sonnet-5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-5.5"]
    }
  }
}

Full field reference in Provider routing.

Common errors

`error.type`	Trigger
`invalid_request_error`	The `fallback` list holds more than 3 models.

Best practice

Pick backups of comparable capability — so output quality stays consistent after a fallback.
Cross-vendor backups — models from one vendor tend to become unavailable together.
Watch how often it fires — frequent fallbacks are a sign the primary model needs replacing.