错误码

先看协议格式

OpenAI 和 Anthropic 风格错误看字符串 error.code。Gemini 风格错误的 error.code 是 HTTP 数字状态，排查时看 error.status、error.message 和 X-Request-Id。

错误格式

Chat Completions、Responses、Images Generations 和 OpenAI 模型列表使用 OpenAI 风格错误。

{
  "error": {
    "message": "账户余额不足，请充值后重试。",
    "type": "billing_error",
    "code": "insufficient_balance",
    "request_id": "req_..."
  },
  "request_id": "req_..."
}

Anthropic Messages、Count Tokens 和 Anthropic 模型列表使用 Anthropic 风格错误。

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "missing API key",
    "code": "api_key_missing"
  }
}

Gemini GenerateContent、streamGenerateContent 和 Gemini 模型列表使用 Google 风格错误。

{
  "error": {
    "code": 400,
    "message": "api_key_conflict",
    "status": "INVALID_ARGUMENT"
  },
  "request_id": "req_..."
}

常见网关错误

下表是网关内部和 OpenAI / Anthropic 兼容响应里的字符串错误码。Gemini 响应不会把这些值放在 error.code 里。

字符串错误码	HTTP	阶段	含义
`api_key_missing`	401	鉴权	没有按协议传用户 API Key
`api_key_invalid`	401	鉴权	用户 API Key 不存在或无效
`api_key_disabled`	403	鉴权	用户 API Key 被禁用
`api_key_conflict`	400	鉴权	混传多种用户 Key Header 且值不一致
`unsupported_header`	400	请求头	请求头不被支持或格式错误，例如多个 `Idempotency-Key` 或非法 `anthropic-version`
`insufficient_balance`	402	余额	用户余额不足，不能发起模型调用
`user_not_found`	404	余额	账号状态异常，需要联系管理员
`request_body_too_large`	413	请求体	请求体超过网关限制
`invalid_request_body`	400	请求体	JSON 或请求结构无效
`model_required`	400	请求体	缺少必填模型名
`model_not_found`	404	分发	模型不存在或当前协议不可用
`stream_not_supported`	400	请求体	当前路径不支持请求体里的 stream=true
`gateway_concurrency_exceeded`	429	并发	网关全局并发达到限制
`user_concurrency_exceeded`	429	并发	当前用户并发达到限制
`upstream_not_configured`	502	上游	没有可用上游候选
`upstream_cooling_down`	503	上游	上游处于冷却期
`upstream_concurrency_exceeded`	429	上游	可用上游账号当前并发已满
`upstream_unavailable`	502	上游	多个上游候选失败后仍不可用
`upstream_network_error`	502	上游	连接上游失败
`upstream_auth_failed`	502	上游	上游认证失败
`upstream_access_denied`	502	上游	上游拒绝访问
`upstream_quota_exceeded`	429	上游	上游账号额度或账单限制导致失败（可冷却自愈，按 429 重试语义）
`upstream_rate_limited`	429	上游	上游返回限流
`upstream_timeout`	504	上游	上游请求超时
`upstream_server_error`	502	上游	上游 5xx 服务异常
`upstream_model_unavailable`	502	上游	上游表示该模型不可用
`upstream_invalid_request`	400	上游	请求参数不被上游接受
`upstream_bad_status`	502	上游	上游返回未映射的非 2xx 状态
`upstream_bad_response`	502	上游	上游响应无法按协议处理
`upstream_stream_read_failed`	502	上游	上游流式响应中断
`client_aborted`	499	客户端	客户端断开连接
`usage_missing`	502	结算	上游响应缺少可结算 usage
`usage_invalid`	502	结算	usage 字段格式不合法
`billing_calculation_failed`	500	结算	网关计费计算失败
`duplicate_request`	409	预检/结算	请求正在处理或已处理（含相同 `Idempotency-Key`）
`billing_settle_failed`	500	结算	网关计费结算失败
`response_too_large`	502	响应	上游响应体超过网关限制
`internal_error`	500	内部	网关内部错误

按阶段处理

先看协议格式

OpenAI 和 Anthropic 风格错误看字符串 error.code。Gemini 风格错误的 error.code 是 HTTP 数字状态，排查时看 error.status、error.message 和 X-Request-Id。

错误格式

Chat Completions、Responses、Images Generations 和 OpenAI 模型列表使用 OpenAI 风格错误。

{
  "error": {
    "message": "账户余额不足，请充值后重试。",
    "type": "billing_error",
    "code": "insufficient_balance",
    "request_id": "req_..."
  },
  "request_id": "req_..."
}

Anthropic Messages、Count Tokens 和 Anthropic 模型列表使用 Anthropic 风格错误。

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "missing API key",
    "code": "api_key_missing"
  }
}

Gemini GenerateContent、streamGenerateContent 和 Gemini 模型列表使用 Google 风格错误。

{
  "error": {
    "code": 400,
    "message": "api_key_conflict",
    "status": "INVALID_ARGUMENT"
  },
  "request_id": "req_..."
}

常见网关错误

下表是网关内部和 OpenAI / Anthropic 兼容响应里的字符串错误码。Gemini 响应不会把这些值放在 error.code 里。

字符串错误码	HTTP	阶段	含义
`api_key_missing`	401	鉴权	没有按协议传用户 API Key
`api_key_invalid`	401	鉴权	用户 API Key 不存在或无效
`api_key_disabled`	403	鉴权	用户 API Key 被禁用
`api_key_conflict`	400	鉴权	混传多种用户 Key Header 且值不一致
`unsupported_header`	400	请求头	请求头不被支持或格式错误，例如多个 `Idempotency-Key` 或非法 `anthropic-version`
`insufficient_balance`	402	余额	用户余额不足，不能发起模型调用
`user_not_found`	404	余额	账号状态异常，需要联系管理员
`request_body_too_large`	413	请求体	请求体超过网关限制
`invalid_request_body`	400	请求体	JSON 或请求结构无效
`model_required`	400	请求体	缺少必填模型名
`model_not_found`	404	分发	模型不存在或当前协议不可用
`stream_not_supported`	400	请求体	当前路径不支持请求体里的 stream=true
`gateway_concurrency_exceeded`	429	并发	网关全局并发达到限制
`user_concurrency_exceeded`	429	并发	当前用户并发达到限制
`upstream_not_configured`	502	上游	没有可用上游候选
`upstream_cooling_down`	503	上游	上游处于冷却期
`upstream_concurrency_exceeded`	429	上游	可用上游账号当前并发已满
`upstream_unavailable`	502	上游	多个上游候选失败后仍不可用
`upstream_network_error`	502	上游	连接上游失败
`upstream_auth_failed`	502	上游	上游认证失败
`upstream_access_denied`	502	上游	上游拒绝访问
`upstream_quota_exceeded`	429	上游	上游账号额度或账单限制导致失败（可冷却自愈，按 429 重试语义）
`upstream_rate_limited`	429	上游	上游返回限流
`upstream_timeout`	504	上游	上游请求超时
`upstream_server_error`	502	上游	上游 5xx 服务异常
`upstream_model_unavailable`	502	上游	上游表示该模型不可用
`upstream_invalid_request`	400	上游	请求参数不被上游接受
`upstream_bad_status`	502	上游	上游返回未映射的非 2xx 状态
`upstream_bad_response`	502	上游	上游响应无法按协议处理
`upstream_stream_read_failed`	502	上游	上游流式响应中断
`client_aborted`	499	客户端	客户端断开连接
`usage_missing`	502	结算	上游响应缺少可结算 usage
`usage_invalid`	502	结算	usage 字段格式不合法
`billing_calculation_failed`	500	结算	网关计费计算失败
`duplicate_request`	409	预检/结算	请求正在处理或已处理（含相同 `Idempotency-Key`）
`billing_settle_failed`	500	结算	网关计费结算失败
`response_too_large`	502	响应	上游响应体超过网关限制
`internal_error`	500	内部	网关内部错误

错误格式

常见网关错误

按阶段处理

本页目录

错误码

错误格式

常见网关错误

按阶段处理

本页目录

错误码

错误格式

常见网关错误

按阶段处理

鉴权错误

余额错误

模型错误

usage 错误

本页目录

错误码

错误格式

常见网关错误

按阶段处理

鉴权错误

余额错误

模型错误

usage 错误

本页目录