参考
完整错误码参考
网关常见错误类型与处理建议（按场景分组，便于检索）。
ToRouter 会在错误响应里给出类型代码（通常对应 JSON 里的 type 字段）。下表整理网关自身常见类型；上游（OpenAI / Anthropic / Gemini）返回的错误仍以上游原文为准，请参阅各供应商文档。
| 类型 | 状态码 | 含义 | 修复 |
|---|
API_KEY_REQUIRED | 401 | 未在请求头携带密钥 | 使用 Authorization: Bearer sk-*** |
INVALID_API_KEY | 401 | Key 不认识 | 排查 typo；可能已被撤销 |
API_KEY_DISABLED | 401 | Key 在 /keys 中被禁用 | 重新启用或新建 |
API_KEY_EXPIRED | 403 | 密钥已超过有效期 | 续期或轮换 |
API_KEY_QUOTA_EXHAUSTED | 429 | 密钥花费已达上限 | 提高上限或轮换 |
USER_NOT_FOUND | 401 | Key 对应的用户不存在 | 联系支持 |
USER_INACTIVE | 401 | 用户被封禁 / 未验证 | 验证邮箱；检查账号状态 |
| 类型 | 状态码 | 含义 | 修复 |
|---|
ACCESS_DENIED | 403 | 客户端 IP 不在 Key 白名单（或在黑名单）；或模型不在 Key 白名单 | 更新 Key 的 IP / 模型限制 |
SUBSCRIPTION_NOT_FOUND | 403 | 密钥需要有效订阅，但当前没有 | 在 /subscriptions 完成订阅 |
INSUFFICIENT_BALANCE | 403 | 按量付费余额 ≤ 0 | 在 /billing/topup 充值 |
| 类型 | 状态码 | 含义 | 修复 |
|---|
顶层 error: "rate limit exceeded" | 429 | Key / IP 请求速率超限 | 退避；提高限额 |
USAGE_LIMIT_EXCEEDED | 429 | 订阅日/周/月窗口超限 | 等待窗口滚动或调整套餐档位 |
SUBSCRIPTION_INVALID | 403 | 订阅暂停 / 取消 / 失效 | 在 /subscriptions 续订 |
| 类型 | 状态码 | 含义 | 修复 |
|---|
api_key_in_query_deprecated | 400 | 在 ?key= 或 ?api_key= 里传 Key（已不支持） | 改放 Authorization 头 |
invalid_request_error（上游透传） | 400 | 上游校验失败 | 修正请求体 |
| 类型 | 状态码 | 含义 | 修复 |
|---|
upstream_unavailable | 502 / 503 | 所有候选渠道均失败 | 退避重试；查 用量仪表盘 或 用量明细 |
upstream_timeout | 504 | 上游未在时限内响应 | 重试；换更小模型或缩短提示词 |
INTERNAL_ERROR | 500 | 网关意外错误 | 重试；持续出现请带上 x-request-id 反馈 |
不同协议（OpenAI / Anthropic / Gemini）的返回形态略有不同，但同一错误的 type 语义一致。
{
"error": {
"type": "API_KEY_EXPIRED",
"code": "API_KEY_EXPIRED",
"message": "API key 已过期"
}
}
type / code：对照上表定位原因。message：面向人的说明；部分历史码为中文。- 响应头
x-request-id：反馈问题时请一并附上。
ToRouter 文档