ToRouter 文档故障排查
上游错误与失败转移
上游供应商出问题时 ToRouter 如何自动切换渠道 —— 以及它无能为力的边界。
ToRouter 在每个供应商前都挂多个上游账号。某条渠道临时失败时，网关会自动切到下一条可用渠道。所有候选都失败时，你才会看到 5xx。
触发自动失败转移的情况
上游返回以下情况时网关会换渠道：
429—— 上游限流401/402/403—— 上游 Key 撤销、封禁或欠费5xx—— 上游服务端错误或过载- 第一个字节响应前的瞬时网络错误
不重试（直接透传给你）的：
400—— 请求体格式错误，换渠道也会被拒404—— 上游没这个模型，同理- 流式响应第一个字节已发给客户端之后的任何错误
流式请求的失败转移只在 首字节写到客户端之前 生效。一旦流中途被上游切断，你看到的是被截断的流，而非重试 —— 没法把两个不同供应商的半截响应安全拼接。
失败转移耗尽时你会看到
{
"error": {
"type": "upstream_unavailable",
"message": "Service temporarily unavailable"
}
}通常是 502 或 503，表示分组轮转中的每条渠道要么出错要么被排除（限流、近期连续失败正在冷却等）。
应对：
- 退避重试 —— 上游瞬时问题通常几秒到几分钟内恢复。
- 在 用量仪表盘 或 用量明细 看失败请求比例与返回码。若某家供应商整体故障（如 OpenAI 区域性宕机），新闻与供应商状态页通常也会同步。
- 换个模型 ——
gpt-5全网挂时，同分组里的claude-opus-4-7或 Qwen 模型可能仍正常。
确定性上游错误（不重试）
部分上游错误会原样透传，因为重试无济于事：
| 上游返回 | 你看到 | 原因 |
|---|---|---|
400 invalid_request_error | 400 带原始消息 | 你的请求体不合法 |
404 model_not_found | 404 | 该模型 slug 在所有上游都无效 |
413 payload_too_large | 413 | 提示词或附件过大 |
415 unsupported_media_type | 415 | 图像/音频格式不支持 |
这些是要修改请求，不是重试。
排查间歇性 5xx
供应商整体健康时仍偶现 502/503，常见原因是某条上游账号在劣化或触发了限流与冷却。用 用量明细 对照模型、渠道列与错误信息排查。