错误码速查

调用网关收到 4xx / 5xx 时，先到本页按状态码定位含义与处理动作；错误体格式（OpenAI / Anthropic / Google 三种风格）与 429、503、502 的具体来源也在本页。想从症状反查见从症状出发排障。

状态码

状态码	error_type	含义	你的处理
400	`bad_request` / `unsupported_feature`	请求 JSON 解析失败；请求的功能/协议对不支持；或请求体语义校验失败（如 Anthropic 请求历史里 `tool_use` id 重复，见下）	检查请求体 JSON 与字段；协议对是否支持见协议互通矩阵；`tool_use` id 重复则去重
401	`authentication_error`	访问密钥无效/禁用，且无匿名兜底	核对 `Authorization`/`x-api-key` 带的是网关访问密钥且已启用
403	`model_access_denied` / `ip_banned`	密钥组未授权该模型；或 IP 被封禁	检查密钥所在组的模型 / 负载均衡器清单是否放行；IP 被封则等封禁超时
404	`model_not_found`	模型不存在（或被 `hide_name` 后用主名访问）	核对模型名；被 `hide_name` 的模型只能用别名访问
413	`payload_too_large`	请求体超过 `max_request_size_mb`	压缩请求体，或调大 `max_request_size_mb`
429	`rate_limit_error` / `service_unavailable` / `handler_queue_full` / `connection_budget_exceeded`	被限流（每密钥/每 IP/上游）、并发占满，或过载准入拒绝（排队深度/连接预算超限）	按下方429 的来源区分；准入拒绝都带 `Retry-After`，按其退避重试即可
500	`internal_error` / `stream_error`	内部错误、流错误、配置错误	看网关运行日志定位；检查配置
502	`bad_gateway` / `upstream_not_found` / `lb_degraded`	上游故障、未找到上游、负载均衡降级、翻译错误、连接错误	检查上游 `base_url` / API key / 连通性（见502 的来源）
503	`service_unavailable` / `overloaded_error` / `upstream_saturated`	无可用节点、流并发上限、全局并发上限，或候选上游全部饱和	见503 的来源；`upstream_saturated` 带 `Retry-After`
504	`timeout` / `outbound_deadline_exceeded`	请求超时，或出站尝试链总时限耗尽	检查上游响应是否过慢、超时配置是否过短，必要时重试

关于「不支持」：不支持的端点/功能/协议对返回 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/*。

json

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

code / param 字段为 null 时省略。

Anthropic 风格

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

json

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

type 映射：

HTTP	anthropic type
400	`invalid_request_error`
401	`authentication_error`
402	`billing_error`
403	`permission_error`
404	`not_found_error`
413	`request_too_large`
429	`rate_limit_error`
500	`api_error`
504	`timeout_error`

未列出的状态码（如 502 / 503）按 api_error 兜底。

Google 风格

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

json

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

status 映射：

HTTP	grpc status
400	`INVALID_ARGUMENT`
401	`UNAUTHENTICATED`
403	`PERMISSION_DENIED`
404	`NOT_FOUND`
413 / 429	`RESOURCE_EXHAUSTED`
500	`INTERNAL`
503	`UNAVAILABLE`
504	`DEADLINE_EXCEEDED`

未列出的状态码（如 402 / 502）按 INTERNAL 兜底。

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

来源	响应体	Retry-After 头
每访问密钥限流	JSON：`{"error":{"message":"access key '…' rate limited on rpm/tpm; retry after Ns","type":"access_key_rate_limited"}}`	有：`Retry-After: <secs>`，另带 `z-rate-limited: access_key:<rpm
每 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>`
过载准入拒绝（排队深度超限 `handler_queue_full` / 数据面连接预算超限 `connection_budget_exceeded`）	JSON（OpenAI/Anthropic/Google 风格，按客户端协议）	有：`Retry-After: <secs>`

所有 429 响应均为 JSON；仅每 IP 限流不带 Retry-After 头。

每个响应（无论成功或报错）还带 z-gateway: <brand>/<version>（如 Protoflux/0.2.1）标识网关构建，以及 z-request-id 用于请求关联。z-gateway 可经 GATEWAY_IDENTITY 置空省略；z-request-id 始终存在。见环境变量参考。

过载准入拒绝是瞬态的：网关本身健康，只是在途请求太多。按 Retry-After 退避重试即可恢复；持续出现说明容量不足，见环境变量配置参考 → 内存准入与溢写与监听与请求限制。

503 的来源

流式并发达上限（streaming.max_concurrent_streams，默认 200）→ 503。
全局并发达上限（server.max_global_concurrency，默认 1000；设 0 关闭）→ 503 overloaded_error。
无可用上游节点（全部被排除）→ 503。
候选上游全部饱和（upstream_saturated）→ 503 + Retry-After。某个上游上挂死（超阈值仍无首响应）的在途请求达到其坏死链接预算时，该上游被排除出候选；候选全被排除即快速失败，而不是排队拖垮健康流量。这是实时在途计数：挂死请求一结束名额即释放，上游恢复立即可用。负载均衡场景下会先在节点间故障转移，节点耗尽才回给客户端。

前两个并发上限不是固定的，是 TOML 配置字段（官方镜像未暴露为环境变量），见配置参考 → 仅配置文件可配的字段。

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

502 的来源

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

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

常见问题

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

Q：429 响应体格式不固定？ 所有 429 响应体现在都是 JSON；仅每 IP 限流不带 Retry-After 头。

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

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

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

错误码速查 ​

状态码 ​

错误响应体格式 ​

OpenAI 风格（默认） ​

Anthropic 风格 ​

Google 风格 ​

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

503 的来源 ​

502 的来源 ​

常见问题 ​

错误码速查

状态码

错误响应体格式

OpenAI 风格（默认）

Anthropic 风格

Google 风格

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

503 的来源

502 的来源

常见问题