文档API 参考错误码

错误码

三种错误信封、错误类别与 HTTP 状态码对照、常见错误一览。

网关对外呈现三家 API 的形状，错误响应也长成对应家的样子——按请求路径决定：/v1/messages* 走 Anthropic 形状，/v1beta/* 走 Google 形状，其余走 OpenAI 形状。这样各家 SDK 的错误解析都能正常工作。

三种错误信封

OpenAI

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Anthropic

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Google

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "status": "UNAUTHENTICATED"
  }
}

错误类别与状态码对照

类别	HTTP	OpenAI `type`	Anthropic `type`	Google `status`
鉴权失败	401	`invalid_request_error`	`authentication_error`	`UNAUTHENTICATED`
权限不足	403	`invalid_request_error`	`permission_error`	`PERMISSION_DENIED`
资源不存在	404	`invalid_request_error`	`not_found_error`	`NOT_FOUND`
入口不受支持	404	`invalid_request_error`	`not_found_error`	`INVALID_ARGUMENT`
请求无效	400	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
限流	429	`rate_limit_error`	`rate_limit_error`	`RESOURCE_EXHAUSTED`
额度/余额不足	402	`insufficient_quota`	`billing_error`	`RESOURCE_EXHAUSTED`
请求体过大	413	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
上游故障	502	`api_error`	`api_error`	`UNAVAILABLE`
过载	503	`server_error`	`overloaded_error`	`UNAVAILABLE`
内部错误	500	`api_error`	`api_error`	`INTERNAL`

常见错误一览

文案 id	HTTP	含义与处置
`key_missing` / `key_invalid`	401	未携带或无效的 API Key，检查鉴权头。
`key_disabled` / `key_expired` / `key_ip_denied`	403	Key 被停用/过期/来源 IP 不在白名单。
`key_quota_exhausted`	402	Key 消费额度用尽，等待周期重置或调整额度。
`balance_exhausted`	402	账户余额不足，充值后重试。
`rpm_exceeded` / `concurrent_exceeded`	429	超出 RPM 或并发上限，退避后重试。
`model_missing`	400	请求缺少 `model` 字段。
`model_not_found` / `model_disabled`	404	模型不存在或已下架，对照模型列表检查拼写。
`no_upstream_for_model`	404	暂无可提供该模型的货源，稍后重试或联系管理员。
`moderation_blocked`	403	内容审核未通过，调整请求内容后重试。
`body_too_large`	413	请求体超过该入口的体积上限，压缩内联媒体或换接口。
`upstream_timeout` / `upstream_unreachable` / `all_upstreams_down`	502	上游超时/不可达/全部熔断，退避后重试。
`server_busy`	503	网关在飞请求总量已满，稍后重试。
`balance_insufficient`	402	余额减去在途请求的预估费用后不足以支付本次请求（见账户余额），充值或等待在途请求结束。
`entry_unsupported`	404	该路径/方法不是网关支持的入口。
`model_rejects_format` / `no_endpoint_for_format`	404	该模型不接受当前入口协议，或暂无货源能承接该协议——改用该模型原生的接口（如 GPT 系走 Responses、Claude 系走 Messages）。
`model_not_schedulable` / `no_group_available`	404 / 403	模型不在你可调度的范围内，或没有对你可见的调度分组，联系管理员。
`client_not_allowed`	403	当前客户端未被允许使用任何分组；自研或未登记的客户端请联系管理员登记。
`account_disabled` / `account_deleted`	403	Key 所属账号已停用或注销。
`privacy_filter_failed`	500	隐私过滤执行失败，请求被拒绝，联系管理员检查过滤规则。
`video_job_missing` / `video_job_not_found` / `video_job_route_gone`	400 / 404 / 502	视频轮询缺少任务 id、任务不存在，或任务所用货源已被移除（见图像与视频）。

错误文案按账号偏好语言本地化（鉴权前按 Accept-Language，默认英文）。程序逻辑请依据 HTTP 状态码与 type/status 字段分支，不要匹配 message 文本。

重试与退避的具体做法见错误处理与重试。