# 失败切换

https://modelportal.ai/docs/fallbacks?lang=zh

`allow_fallbacks` 决定首选报价失败时，要不要换同一模型的下一个报价再试。是否切换由你决定，平台默认不切换。

## 默认：锁定首选报价

`allow_fallbacks` 默认是 `false`。平台按[默认路由规则](/docs/default-routing)或你的 `provider` 设置排出报价顺序，只尝试排在第一位的那个；它失败时直接返回错误，不会换到别的报价，更不会换成别的模型。

失败的尝试不向你收费。上游出错或超时返回 502 `upstream_failed`，上游限流返回 429 `capacity_exhausted` 并带 `Retry-After`。

## 开启切换

在 `provider` 里写 `"allow_fallbacks": true`，或在账户、密钥的默认偏好里打开。生效值按「请求 > 密钥 > 账户 > 平台默认（`false`）」确定。

开启后，首选报价失败时按顺序换下一个报价，一次请求最多尝试 3 个报价。会触发切换的错误：

- 连接失败、超时
- HTTP 429、HTTP 5xx
- 上游认证失败
- 这个报价特有的错误：超出上下文长度、不支持某个参数、供应商自己的内容策略拒绝

其他请求错误（例如普通的 400、413）不切换，直接返回给你，换一个报价也是同样的结果。所有尝试都失败时返回 502 `upstream_failed`。

只有承接成功的那次尝试计费，按承接它的报价的价格结算；失败的尝试不收费，见[尝试与结算](/docs/attempts)。客户端断开连接后，平台立即关闭上游连接，不再切换。

## 流式请求

流式请求只在首个内容事件之前可以切换。首个内容事件是第一个带非空文本、推理内容或工具调用的事件，在它之前上游发出的空事件不会转发给你。内容开始输出后上游再中断，平台用 SSE 错误事件结束这次响应，不再切换，按已经产生的用量计费。

## 超时

首个内容事件到达之前，所有尝试共用一个总超时，默认 600 秒，用完后不再开始新的尝试。首个内容事件之后不再受这个总超时限制，改用事件间空闲超时，默认 120 秒：上游超过 120 秒没有新事件才算超时。流式输出另有 60 分钟的总时长上限。非流式请求的整次调用（包括所有尝试）都受 600 秒总超时约束。

## 切换不会放宽约束

无论是否切换，每次尝试都取自同一组候选报价：数据政策、数据处理地区、量化精度等限制对每次尝试同样生效，只在同一个模型的报价之间进行。