# Fallback — Switch to a Backup Model

Source: https://ofox.ai/docs/develop/advanced/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**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-6.1-sol", "google/gemini-3.8-flash"]
      }
    }
  }'
```

**Python**

```python filename="fallback.py"
client.chat.completions.create(
    model="anthropic/claude-sonnet-5.5",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "extra_body": {
            "provider": {
                "fallback": ["openai/gpt-6.1-sol", "google/gemini-3.8-flash"],
            }
        }
    },
)
```

**TypeScript**

```typescript filename="fallback.ts"
await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5.5',
  messages: [{ role: 'user', content: '...' }],
  extra_body: {
    provider: {
      fallback: ['openai/gpt-6.1-sol', 'google/gemini-3.8-flash'],
    },
  },
} 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:

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

Full field reference in [Provider routing](https://ofox.ai/docs/develop/advanced/provider-routing).

## Common errors

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

## Best practice

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