错误码

错误码

错误来源

来源格式如何识别
Router 自身(认证、权限、额度、限速、请求体)text/plain,单行文本正文为下表中的固定文本
风控封禁JSONerror.type 为 cyber_abuse_guard,见风控封禁
模型服务商服务商原样的状态码与 JSON结构与服务商官方文档一致
上游不可达502,正文为空连接失败或上游响应无法处理

部分部署会把普通 HTTP 请求中 ≥ 400 的上游错误正文统一替换为 {"error": {"message": "The API is temporarily overloaded.", "status": N}},以免暴露上游细节;风控相关响应不受此影响,Realtime 与 Live 建会接口同样不受影响。

认证

状态码正文处理
401You 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)
401UnauthorizedKey 不存在或已被轮换
429Too many unauthorized requests. Please try again later.该 IP 认证失败过多,被临时限制 2–15 分钟
403Your account is inactive. Please contact support.账号已停用

访问控制

状态码正文
403Access denied: Your IP address <ip> is not authorized.
403Permission restricted: You don't have access to the requested resource '<path>'.
403Access denied: You are not authorized to use the '<model>' model
400The 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)。封禁按账号生效,重试不会缩短封禁;到期后自动恢复。如需提前解除,请联系服务提供方。

余额与额度

状态码正文说明
401Insufficient balance. $<balance> [...]本次检查发现余额低于冻结阈值,账号随即被冻结
429Your API access has been temporarily suspended, please check your plan and billing details.账号已冻结;充值后自动恢复
429You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ...超出日额度,次日恢复
429You exceeded your current quota, please check your plan and billing details. CreditUsed / HardLimit: ...超出月额度,次月恢复

账号被冻结或超出额度时,GET /dashboard/* 与 /user/balance 仍可访问。订阅账号(role 为 3)超出日或月额度时,若有按量余额,会自动改用按量余额继续调用,此时不再返回上述额度错误。

限速

状态码正文恢复时间
429Too many requests, Rate limit <scope> reached, Limit: <rpm>/<rph>/<rpd> (RPM/RPH/RPD).RPM 1 分钟、RPH 1 小时、RPD 次日零点
429Too many requests, Token limit <scope> reached, Limit: <tpm>/<tph>/<tpd> (TPM/TPH/TPD).同上
429Too many requests for model '<model>', Rate limit RPM <n> reached.(RPH、RPD 同理)同上
429TPM exceeded for model '<model>': <n>.(TPH、TPD 同理)同上

Token 限额按已发生的用量累计:本次请求是否放行取决于此前的消耗是否已超过限额。role 为 0 或 1 的账号不执行日、月额度与限速检查。

请求

状态码正文
413request body too large
400Error reading request body: ...、error parsing multipart form: ...、Error creating <encoding> reader: ...
400invalid video request_id
400invalid or unavailable Codex file; upload it again with the current account,以及 Codex 文件引用的其他校验信息,见《Router API》
400Live sessions do not accept query parameters; put the model in session.start、Public Live sessions require gpt-live-1
404404 page not found(未知的 /dashboard/* 路径)

上游与可用性

状态码正文说明
500No available key该模型对应的 Level 中没有可用上游
502(空)上游不可达
502WebSocket upstream failureWebSocket 握手阶段上游失败
503video generation account unavailable、file account unavailable、No available Codex file account、No available Realtime provider key绑定的上游账号不可用
503No OpenAI Live project key at the configured model level套餐上游不是 OpenAI 官方 API,不能使用 /v1/live/sessions;Codex 专营套餐请改用 /v1/live,见《WebSocket 与实时接口》
503request body memory budget exhausted服务当前处理的请求体总量已达上限,稍后重试
503Server is shutting down实例正在优雅关闭
503{"error": {"code": "codex_models_unavailable", ...}}Codex 客户端的原生模型目录暂不可用

POST 请求遇到可重试的上游错误时,Router 已在服务端换上游重试;你收到错误意味着重试已用尽。

账号管理接口

状态码正文说明
403Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>.不满足管理者条件
403Forbidden目标不在你的账号树内
404User not found目标不存在
409User already exists账号名或邮箱已占用
429API Key was regenerated recently. Please try again later.10 分钟内重复轮换 Key

处理建议

  • 只对 429、502、503 与网络错误做有限次重试,使用指数退避加随机抖动,并遵守响应中的 Retry-After(如有)。
  • 401、403、413 与额度类 429 不应自动重试,应提示用户检查 Key、权限或余额。
  • 收到风控封禁响应后停止重试,等待 until_at。
  • 记录状态码与响应正文以便排查,但不要记录完整的 API Key。

相关文档