错误码速查

调用网关时可能收到的 HTTP 状态码、错误体格式与含义。

状态码

状态码	error_type	含义
400	bad_request / unsupported_feature	请求 JSON 解析失败；请求的功能/协议对不支持；或请求体语义校验失败（如 Anthropic 请求历史里 tool_use id 重复，见下）
401	authentication_error	访问密钥无效/禁用，且无匿名兜底
403	model_access_denied / ip_banned	密钥组未授权该模型；或 IP 被封禁
404	model_not_found	模型不存在（或被 hide_name 后用主名访问）
413	payload_too_large	请求体超过 max_request_size_mb
429	rate_limit_error / service_unavailable	被限流（每密钥/每 IP/上游）或并发占满
500	internal_error / stream_error	内部错误、流错误、配置错误
502	bad_gateway / upstream_not_found / lb_degraded	上游故障、未找到上游、负载均衡降级、翻译错误、连接错误
503	service_unavailable / overloaded_error	无可用节点、流并发上限、全局并发上限
504	timeout	请求超时

关于「不支持」：不支持的端点/功能/协议对返回 400（unsupported_feature），模型不存在返回 404。网关不返回 501。

关于 tool_use id 唯一性：Anthropic Messages 契约要求历史里每个 tool_use 块的 id 全局唯一。网关对发往 /v1/messages 的请求做同样校验——历史含重复 tool_use id 时回 400，Anthropic 客户端收到 invalid_request_error、错误消息形如 tool_use ids must be unique: duplicate id "…"，与直接调用 Anthropic 官方 API 的行为一致。响应方向上网关为每个 tool_use 块合成全局唯一的 toolu_ id，客户端原样回显即可，无需关心上游分配的原始 id。

错误响应体格式

错误体格式按客户端协议走，与上游无关：

OpenAI 风格（默认）

适用于 /v1/chat/completions、/v1/responses、/v1/images/*、/v1/embeddings、/v1/audio/*、/v1/rerank、/v2/rerank、/v3/*、/v1/services/*。

{
  "error": {
    "message": "...",
    "type": "<error_type>"
  }
}

code / param 字段为 null 时省略。

Anthropic 风格

适用于 /v1/messages、/v1/messages/count_tokens。

{
  "type": "error",
  "error": {
    "type": "<anthropic_type>",
    "message": "..."
  },
  "request_id": "..."
}

type 映射：

HTTP	anthropic type
400	invalid_request_error
401	authentication_error
403	permission_error
404	not_found_error
429	rate_limit_error
504	timeout_error

Google 风格

适用于 /v1beta/models/*、/v1/models/*。

{
  "error": {
    "code": 429,
    "message": "...",
    "status": "<grpc_status>"
  }
}

status 映射：

HTTP	grpc status
400	INVALID_ARGUMENT
401	UNAUTHENTICATED
403	PERMISSION_DENIED
413 / 429	RESOURCE_EXHAUSTED
503	UNAVAILABLE
504	DEADLINE_EXCEEDED

429 的三种来源（体格式不同，解析需兼容）

来源	响应体	Retry-After 头
每访问密钥限流	纯文本：Rate limit exceeded (N requests per Ns). Retry after Ns	无
每 IP 限流	JSON：{"error":{"message":"Rate limit exceeded for IP (N/min)","type":"rate_limit_error"}}	无
上游限流	JSON（OpenAI/Anthropic/Google 风格，按客户端协议）	有：Retry-After: <secs>，另带 z-rate-limited: <upstream>:<dimension>

调用方解析 429 时，既要能解析 JSON，也要能解析纯文本（每密钥限流是纯文本）。

503 的来源

• 流式并发达上限（固定上限，默认 200）→ 503。
• 全局并发达上限（固定上限，默认 1000）→ 503 overloaded_error。
• 无可用上游节点（全部被排除）→ 503。

无凭证且无匿名兜底返回 401（见上表），不是 503。

502 的来源

• 上游返回错误、连接错误、翻译错误。
• 负载均衡器降级（所有节点故障）。
• 静态绑定的单上游故障（不跨节点转移）。

配了负载均衡且 retry_on_different_node=true 时，单节点故障会自动转移，调用方通常看不到 502；持续 502 说明所有节点都不可用。

常见问题

Q：网关返回 501？ 不返回 501。不支持的端点/功能/协议对返回 400（unsupported_feature），模型不存在返回 404。

Q：429 响应体格式不固定？ 是的：每密钥限流返回纯文本，每 IP 限流和上游限流返回 JSON。解析 429 时要兼容纯文本与 JSON 两种体。

Q：502 持续不停？ 所有节点都不可用。配了负载均衡且 retry_on_different_node=true 时单节点故障自动转移，调用方通常看不到 502。持续 502 说明上游确实全挂了，检查上游配置和连接。

Q：503 是限流还是过载？ 两种可能：流式并发达上限、全局并发达上限、无可用上游节点。看响应体的 error.type 区分（rate_limit_error vs service_unavailable vs overloaded_error）。无凭证返回的是 401，不在此列。

下一步：端点 · 认证 · 协议互通 看完整端点清单；客户端接入与网关差异 看各 SDK 接法和重试建议；协议互通矩阵 看协议对支持情况。