> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/error-codes · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 错误码速查

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

## 状态码

| 状态码 | error_type | 含义 | 你的处理 |
|--------|-----------|------|---------|
| 400 | `bad_request` / `unsupported_feature` | 请求 JSON 解析失败；请求的功能/协议对不支持；或请求体语义校验失败（如 Anthropic 请求历史里 `tool_use` id 重复，见下） | 检查请求体 JSON 与字段；协议对是否支持见[协议互通矩阵](/zh-CN/reference/protocol-matrix.md)；`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 的来源](#source-of-429)区分；准入拒绝都带 `Retry-After`，按其退避重试即可 |
| 500 | `internal_error` / `stream_error` | 内部错误、流错误、配置错误 | 看网关运行日志定位；检查配置 |
| 502 | `bad_gateway` / `upstream_not_found` / `lb_degraded` | 上游故障、未找到上游、负载均衡降级、翻译错误、连接错误 | 检查上游 `base_url` / API key / 连通性（见[502 的来源](#source-of-502)） |
| 503 | `service_unavailable` / `overloaded_error` / `upstream_saturated` | 无可用节点、流并发上限、全局并发上限，或候选上游全部饱和 | 见[503 的来源](#source-of-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 的来源（体格式不同，解析需兼容） {#source-of-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|tpm>:<scope>` |
| 每 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` 始终存在。见 [环境变量参考](/zh-CN/reference/configuration.md)。

> 过载准入拒绝是**瞬态**的：网关本身健康，只是在途请求太多。按 `Retry-After` 退避重试即可恢复；持续出现说明容量不足，见 [环境变量配置参考 → 内存准入与溢写](/zh-CN/reference/configuration.md#memory-admission-spill) 与 [监听与请求限制](/zh-CN/reference/configuration.md#listen-and-request-limits)。

## 503 的来源 {#source-of-503}

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

> 前两个并发上限**不是固定的**，是 TOML 配置字段（官方镜像未暴露为环境变量），见 [配置参考 → 仅配置文件可配的字段](/zh-CN/reference/configuration.md#config-file-only-fields)。

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

## 502 的来源 {#source-of-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，不在此列。

**下一步**：[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点清单；[客户端接入与网关差异](/zh-CN/reference/clients-and-gateway-diffs.md) 看各 SDK 接法和重试建议；[协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 看协议对支持情况。