错误码
错误码
错误来源
| 来源 | 格式 | 如何识别 |
|---|
| Router 自身(认证、权限、额度、限速、请求体) | text/plain,单行文本 | 正文为下表中的固定文本 |
| 风控封禁 | JSON | error.type 为 cyber_abuse_guard,见风控封禁 |
| 模型服务商 | 服务商原样的状态码与 JSON | 结构与服务商官方文档一致 |
| 上游不可达 | 502,正文为空 | 连接失败或上游响应无法处理 |
部分部署会把普通 HTTP 请求中 ≥ 400 的上游错误正文统一替换为 {"error": {"message": "The API is temporarily overloaded.", "status": N}},以免暴露上游细节;风控相关响应不受此影响,Realtime 与 Live 建会接口同样不受影响。
认证
| 状态码 | 正文 | 处理 |
|---|
401 | You didn't provide an API key. You need to provide your API key in an Authorization header using Bearer auth (i.e. Authorization: Bearer YOUR_KEY) | 模型接口:未携带 Key,或 Key 不是 51 位 sk-Xvs 格式(账号管理接口在同样情况下返回 401 Unauthorized) |
401 | Unauthorized | Key 不存在或已被轮换 |
429 | Too many unauthorized requests. Please try again later. | 该 IP 认证失败过多,被临时限制 2–15 分钟 |
403 | Your account is inactive. Please contact support. | 账号已停用 |
访问控制
| 状态码 | 正文 |
|---|
403 | Access denied: Your IP address <ip> is not authorized. |
403 | Permission restricted: You don't have access to the requested resource '<path>'. |
403 | Access denied: You are not authorized to use the '<model>' model |
400 | The model `<model>` is not available on this endpoint.(DeepSeek 计费模型用于错误的接口) |
风控封禁
风控启用时,当模型服务商返回网络安全使用政策类响应(错误码 cyber_policy,或带有 cyber 用途标记的 safety_buffering 事件)时,触发该响应的请求会原样返回给你,随后账号被临时封禁 36 小时。封禁期间,除 GET /v1/models、GET /models 与 /dashboard/* 外的全部请求(包括 WebSocket 与实时会话的后续请求)都会返回:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": {
"message": "User is temporarily blocked after a Cyber abuse policy response",
"type": "cyber_abuse_guard",
"code": "temporary_blocked",
"user_id": 42,
"until_at": "2026-11-21T18:00:00+08:00"
}
}
until_at 为封禁到期时间(RFC 3339)。封禁按账号生效,重试不会缩短封禁;到期后自动恢复。如需提前解除,请联系服务提供方。
余额与额度
| 状态码 | 正文 | 说明 |
|---|
401 | Insufficient balance. $<balance> [...] | 本次检查发现余额低于冻结阈值,账号随即被冻结 |
429 | Your API access has been temporarily suspended, please check your plan and billing details. | 账号已冻结;充值后自动恢复 |
429 | You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ... | 超出日额度,次日恢复 |
429 | You exceeded your current quota, please check your plan and billing details. CreditUsed / HardLimit: ... | 超出月额度,次月恢复 |
账号被冻结或超出额度时,GET /dashboard/* 与 /user/balance 仍可访问。订阅账号(role 为 3)超出日或月额度时,若有按量余额,会自动改用按量余额继续调用,此时不再返回上述额度错误。
限速
| 状态码 | 正文 | 恢复时间 |
|---|
429 | Too many requests, Rate limit <scope> reached, Limit: <rpm>/<rph>/<rpd> (RPM/RPH/RPD). | RPM 1 分钟、RPH 1 小时、RPD 次日零点 |
429 | Too many requests, Token limit <scope> reached, Limit: <tpm>/<tph>/<tpd> (TPM/TPH/TPD). | 同上 |
429 | Too many requests for model '<model>', Rate limit RPM <n> reached.(RPH、RPD 同理) | 同上 |
429 | TPM exceeded for model '<model>': <n>.(TPH、TPD 同理) | 同上 |
Token 限额按已发生的用量累计:本次请求是否放行取决于此前的消耗是否已超过限额。role 为 0 或 1 的账号不执行日、月额度与限速检查。
请求
| 状态码 | 正文 |
|---|
413 | request body too large |
400 | Error reading request body: ...、error parsing multipart form: ...、Error creating <encoding> reader: ... |
400 | invalid video request_id |
400 | invalid or unavailable Codex file; upload it again with the current account,以及 Codex 文件引用的其他校验信息,见《Router API》 |
400 | Live sessions do not accept query parameters; put the model in session.start、Public Live sessions require gpt-live-1 |
404 | 404 page not found(未知的 /dashboard/* 路径) |
上游与可用性
| 状态码 | 正文 | 说明 |
|---|
500 | No available key | 该模型对应的 Level 中没有可用上游 |
502 | (空) | 上游不可达 |
502 | WebSocket upstream failure | WebSocket 握手阶段上游失败 |
503 | video generation account unavailable、file account unavailable、No available Codex file account、No available Realtime provider key | 绑定的上游账号不可用 |
503 | No OpenAI Live project key at the configured model level | 套餐上游不是 OpenAI 官方 API,不能使用 /v1/live/sessions;Codex 专营套餐请改用 /v1/live,见《WebSocket 与实时接口》 |
503 | request body memory budget exhausted | 服务当前处理的请求体总量已达上限,稍后重试 |
503 | Server is shutting down | 实例正在优雅关闭 |
503 | {"error": {"code": "codex_models_unavailable", ...}} | Codex 客户端的原生模型目录暂不可用 |
POST 请求遇到可重试的上游错误时,Router 已在服务端换上游重试;你收到错误意味着重试已用尽。
账号管理接口
| 状态码 | 正文 | 说明 |
|---|
403 | Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>. | 不满足管理者条件 |
403 | Forbidden | 目标不在你的账号树内 |
404 | User not found | 目标不存在 |
409 | User already exists | 账号名或邮箱已占用 |
429 | API Key was regenerated recently. Please try again later. | 10 分钟内重复轮换 Key |
处理建议
- 只对
429、502、503 与网络错误做有限次重试,使用指数退避加随机抖动,并遵守响应中的 Retry-After(如有)。 401、403、413 与额度类 429 不应自动重试,应提示用户检查 Key、权限或余额。- 收到风控封禁响应后停止重试,等待
until_at。 - 记录状态码与响应正文以便排查,但不要记录完整的 API Key。
相关文档