文档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	网关在飞请求总量已满，稍后重试。

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

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