ToRouter 文档故障排查
常见 HTTP 错误
400 / 401 / 403 / 404 / 429 / 5xx 响应的速查表，以及对应的修复方法。
ToRouter 遵循标准 HTTP 语义。状态码会告诉你问题出在请求、Key、配额还是上游供应商。
| 状态码 | 在 ToRouter 中的含义 | 修复建议 |
|---|---|---|
| 400 | 请求体格式错误、model 名称无效、参数不被该模型支持 | 校验 JSON；在 /models 查模型 slug；去掉不支持的字段 |
| 401 | API key 缺失、格式错误或未知（API_KEY_REQUIRED、INVALID_API_KEY、API_KEY_DISABLED、USER_INACTIVE） | 检查 Authorization: Bearer sk-*** 头；确认 Key 已启用 |
| 402 | 按量计费余额不足 | 在「计费 → 充值」中充值 |
| 403 | 拒绝访问（ACCESS_DENIED，IP 白名单未匹配）、API_KEY_EXPIRED、SUBSCRIPTION_NOT_FOUND、INSUFFICIENT_BALANCE、模型不在 Key 白名单 | 调整 Key 的 IP / 模型白名单；续期；订阅分组 |
| 404 | 模型不在你所订阅分组的目录中，或路径不存在 | 在 /models 看分组开放了哪些模型；确认路径与协议匹配（OpenAI / Anthropic / Gemini） |
| 429 | 触发限流（rate limit exceeded）、API_KEY_QUOTA_EXHAUSTED、订阅的日/周/月窗口超限 | 见 被限流 |
| 500 | ToRouter 内部错误 —— 退避重试 | 重试；持续出现请带上响应头 x-request-id 反馈 |
| 502 | 所有候选上游均失败 | 见 上游错误与失败转移 |
| 503 | 暂时不可用 —— 当前没有可用渠道 | 重试；在 /dashboard 查看渠道健康 |
| 504 | 上游超时 | 重试；考虑换更小的模型或缩短提示词 |
响应结构
ToRouter 的错误以 JSON 返回，至少包含 error 字段。具体结构与你调用的协议（OpenAI / Anthropic / Gemini）一致，内部嵌入 ToRouter 的错误码。
{
"error": {
"message": "API key 已过期",
"type": "API_KEY_EXPIRED",
"code": "API_KEY_EXPIRED"
}
}始终记录响应头 x-request-id，方便支持团队追踪请求经过的完整网关路径。