# 故障回退 — 自动切换备选模型

Source: https://ofox.io/zh/docs/develop/advanced/fallback

`provider.fallback` 用于列出备选模型。主模型在上游调用失败时，按列表顺序依次尝试。

## 配置方式

`fallback` 接受一个模型 ID 数组，与 `type` 同级挂在 `provider` 下。**最多 3 个模型**，超出返回 `400`。

**cURL**

```bash filename="Terminal"
curl https://api.ofox.io/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)
```

使用官方 OpenAI SDK 时，`extra_body` 需作为请求体中的字面量键存在。TypeScript SDK 在参数对象中直接书写 `extra_body` 即可；Python SDK 的 `extra_body=` 参数会将其内容合并至请求体顶层，因此需额外嵌套一层，或改用请求头传递。

## 什么情况下会降级

降级只覆盖路由选定渠道之后发生的失败：

| 情况 | 行为 |
|------|------|
| 上游供应商返回错误 | 降级 —— 按顺序尝试列表中的模型，返回第一个成功的响应 |
| 路由期失败（模型不存在，或指定的供应商不承载该模型） | **不降级** —— 请求直接终止 |

第二行值得明确写出来：把 `provider.type` 指定到不承载该模型的供应商，返回 `400 provider_type_unavailable`；指定不存在的模型，返回 `404 model_not_found`。两者都不会走到 fallback 列表。具体哪些上游错误会触发降级，以网关的实际行为为准，文档不列固定清单。

## 与指定供应商组合

`fallback` 与 `type` 可以同时传 —— `type` 约束**主模型**跑在哪个供应商上，`fallback` 负责主模型失败之后的事：

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

字段完整说明见 [供应商路由](https://ofox.io/zh/docs/develop/advanced/provider-routing)。

## 常见错误

| `error.type` | 触发条件 |
|------|------|
| `invalid_request_error` | `fallback` 列表超过 3 个模型。 |

## 最佳实践

1. **选择能力相近的备选模型** —— 确保降级后输出质量一致。
2. **跨厂商备选** —— 同一厂商的模型往往同时不可用。
3. **监控降级频率** —— 频繁降级说明主模型该换了。