失败重试与备用模型
一次调用失败时，网关会在开始向客户端输出内容之前，自动改用下一个凭证、通道或模型，直到成功或候选用完。客户端只收到最终结果，所以一次请求成功，不代表过程中没有发生上游失败；每次实际尝试都记录在请求日志中。
回退顺序
直接调用模型 ID 时，网关按以下顺序尝试：
- 按「多渠道选路策略」排好序的第 1 个通道：
- 先用该通道下的 BYOK 凭证，按你在 BYOK 中设置的顺序；
- 再用该通道的平台凭证（工作空间在模型广场开通了该通道时）。
- 第 2 个、第 3 个……通道，每个通道内同样先用 BYOK 凭证、再用平台凭证。
- 最后是工作空间「默认模型」的通道（设置了默认模型、且与请求的模型不同时）。
- 哪些失败会换下一个：上游返回任何非 2xx 状态码、连接上游失败或等待超时，都会换下一个凭证或通道。
- 已达限额的凭证先被跳过：达到限额的凭证或通道在排序时就被移出。全部因限额被移出、也没有默认模型可以接手时，返回 429
all upstream credentials for this model are rate limited。 - 全部失败时：返回最后一次尝试的上游状态码和响应体。
- 通道排序与 BYOK 偏好：见通道选择与路由策略。「优先使用此 Channel」只把通道提到最前，失败后照常回退；「仅用此 BYOK」会限制回退范围，见下表。
跨模型的备用模型
需要在一个模型失败后改用另一个模型时，有两种做法：
lyrouter/auto 也按模型依次尝试，最后同样是工作空间默认模型。
图 1：在虚拟模型配置中确认主模型和备用模型；备用模型还需支持原请求的关键能力。 截图为演示数据，点击图片可查看原图。
备用模型必须支持原请求使用的接口、输入类型和工具调用。网关不会因为备用模型能力不足而跳过它；模型不支持请求的输入时，请求会直接返回 400，不再尝试后面的模型。
不会回退的情况
| 情况 | 结果 |
|---|---|
流式请求（stream: true）已经开始输出后，上游中断或超时 |
不换通道。在流末尾补发一个错误事件后结束：Chat Completions 中 error.code 为 stream_interrupted，Responses 中是 response.failed 事件，见超时与流式中断 |
| 通道开启了「仅用此 BYOK」 | 只尝试该通道的 BYOK 凭证，全部失败即结束，不使用平台凭证、其他通道或默认模型。通过虚拟模型或 lyrouter/auto 调用时，仍会尝试下一个候选模型，但不再回退到默认模型 |
网关拒绝了这次尝试：余额不足（402）、安全围栏的模型策略禁止所选模型（403 Request blocked by guardrail policy）、所选模型不支持当前接口或输入（400 unsupported_model_api、unsupported_model_input） |
直接返回该错误，不换下一个候选 |
上游以约定格式声明生成失败（error.code 为 upstream_rejected 或 upstream_no_artifact，常见于图像生成） |
直接返回，不换通道 |
| 图像、视频和语音接口 | 只在同一模型的通道之间回退，不改用默认模型或其他模型 |
客户端的重试
网关已经在内部回退，客户端不需要对每个错误都自动重试：
- 对 400、401、402、403 这类请求或配置问题，修正后再调用；同样的请求重试会得到同样的结果。
- 对 429 和 503，按429：限流与配额和模型不可用的说明处理，使用有上限的退避重试。
- 同一个 API Key 在 60 秒内至少有 100 次请求、且 90% 以上失败时会被临时熔断，网关自己返回的 4xx 也计入失败。持续失败的程序不停重试，会很快把密钥熔断，多次熔断后会被永久封禁。
定位一次回退
怎么判断一次请求是否发生了回退？
答： 在请求日志中打开这条记录，查看「路由追踪」中的「上游调用尝试」，它记录每一次实际尝试的状态码、耗时和换下一个候选的原因；只尝试了一次的请求不显示这一块。「各阶段耗时」的「④ 上游调用」旁显示「N 次尝试」时，也说明发生过重试。「全部候选」只是排好序的候选列表，不能证明候选都被调用过。「路由追踪」只对账号管理员和工作空间管理员显示，其他成员可以把日志详情顶部的 Request ID 发给账号管理员协助核查。
图 2：日志详情的路由追踪显示实际模型、服务商和上游调用尝试。 截图为演示数据，点击图片可查看原图。
为什么回答来自请求之外的模型？
答： 请求的模型全部失败，或在本工作空间未开通时，网关会改用工作空间的默认模型。日志的「模型（实际）」显示实际回答的模型。不需要这种兜底时，请账号管理员在智能路由中清空默认模型。
流式输出已经开始，断开后可以直接重试吗？
答： 网关不会在输出开始后换通道。收到 stream_interrupted 错误事件或 response.failed 事件，或没有收到结束标记（data: [DONE]、message_stop 或 response.completed）时，应把这次调用视为失败。重新调用可能重复生成内容或再次触发工具，应用需要自行处理取消、重试和去重，详见超时与流式中断。