title: AI Gateway 错误码说明 description: AI Gateway 统一错误响应结构、错误码、上游重试记录和排查方式

错误码说明

本页说明 AI Gateway 请求失败时返回的统一错误结构和错误码。无论错误发生在网关侧还是上游模型供应商侧，AI Gateway 都会返回统一的 JSON 结构，便于业务程序自动识别并处理。

一、错误响应结构

所有错误都会返回一个 

error
error
对象：

{ "error": { "code": "GATEWAY_MISSING_VIRTUAL_KEY", "message": "[G2] Virtual key not provided. path=/v1/chat/completions, requestId=req-abc", "source": "gateway", "retry_history": null } }

字段说明：

字段说明
code
code
机器可读的错误码，建议作为程序判断依据。
message
message
可读错误描述，通常包含 
requestId
requestId
等排查信息。开头的 
[G2]
[G2]
为内部追踪标识，可忽略。
source
source
错误来源。
gateway
gateway
表示请求未到达任何模型即被拦截；
upstream
upstream
表示请求已转发，但所有上游端点均失败。
retry_history
retry_history
当 
source = upstream
source = upstream
时存在，按顺序列出每次上游尝试；其他情况通常为 
null
null
。

二、快速判断问题位置

先看 

source
source
字段：

source含义排查方向
gateway
gateway
请求在 AI Gateway 网关侧被拦截，没有转发到模型供应商。检查 API Key、配额、请求路径、模型名称、路由配置。
upstream
upstream
请求已转发到一个或多个供应商端点，但全部失败。查看 
retry_history
retry_history
中每次尝试的状态码和上游返回体。

三、是否建议重试

HTTP 状态含义是否建议重试
400
400
请求格式、路径、模型或路由参数有误不建议直接重试，应先修正请求
401
401
鉴权失败不建议直接重试，应检查 API Key
403
403
账务、配额或权限问题不建议直接重试，应处理权限、账务或配额
429
429
请求频率或并发超过限制可以退避重试，并降低并发
500
500
网关内部异常可以稍后重试；持续出现请联系支持
502
502
所有上游端点均失败可以稍后重试；持续出现应检查 
retry_history
retry_history

四、网关错误

以下错误发生在请求被转发到任何模型之前，

source
source
通常为 
gateway
gateway
。

鉴权与密钥

错误码HTTP说明处理建议
GATEWAY_MISSING_VIRTUAL_KEY
GATEWAY_MISSING_VIRTUAL_KEY
401请求中未提供虚拟密钥。在请求头中加入 
Authorization: Bearer <API_KEY>
Authorization: Bearer <API_KEY>
或 
x-api-key: <API_KEY>
x-api-key: <API_KEY>
。
GATEWAY_INVALID_VIRTUAL_KEY
GATEWAY_INVALID_VIRTUAL_KEY
401提供的虚拟密钥不存在或格式不正确。核对 API Key 是否正确，并确认已在 AI Gateway 后台创建。
GATEWAY_VIRTUAL_KEY_DISABLED
GATEWAY_VIRTUAL_KEY_DISABLED
401虚拟密钥存在但已被停用。在 
API KEY 管理
API KEY 管理
中启用该 Key，或更换有效 Key。

账务与配额

错误码HTTP说明处理建议
GATEWAY_TENANT_OVERDUE
GATEWAY_TENANT_OVERDUE
403租户账户存在未结清账单，调用已被暂停。结清欠款后恢复服务。
GATEWAY_TENANT_OVER_QUOTA
GATEWAY_TENANT_OVER_QUOTA
403租户超出当前计费周期的用量配额。等待下一周期，降低调用量，或申请提升配额。

路由与配置

错误码HTTP说明处理建议
GATEWAY_MISSING_ACTUAL_PATH
GATEWAY_MISSING_ACTUAL_PATH
400网关无法从请求 URL 中解析出转发路径。确认请求 URL 符合网关地址格式，不要漏写或重复拼接路径。
GATEWAY_MODEL_NOT_RESOLVED
GATEWAY_MODEL_NOT_RESOLVED
400网关无法从请求体中确定要路由的模型。确认请求体包含有效的 
model
model
字段。
GATEWAY_NO_UPSTREAM_CANDIDATES
GATEWAY_NO_UPSTREAM_CANDIDATES
400所请求的模型和协议组合没有任何可用上游端点。检查模型名称、模型类型、供应商接入点和路由策略。

内部错误

错误码HTTP说明处理建议
GATEWAY_INTERNAL_ENDPOINTS_BAD_REQUEST
GATEWAY_INTERNAL_ENDPOINTS_BAD_REQUEST
400调用内部端点接口时缺少必填字段。一般用户不会遇到；若出现，请联系支持。
GATEWAY_INTERNAL_API_EXCEPTION
GATEWAY_INTERNAL_API_EXCEPTION
500网关内部接口发生未预期异常。可重试；持续出现请携带 
requestId
requestId
联系支持。

五、上游错误

以下错误发生在请求被转发到一个或多个模型端点之后，但所有尝试均失败，

source
source
通常为 
upstream
upstream
。

错误码HTTP说明处理建议
UPSTREAM_ALL_FAILED
UPSTREAM_ALL_FAILED
502所有候选上游端点均返回错误或不可达。查看 
retry_history
retry_history
，确认失败供应商、状态码和原始错误体。

六、retry_history 结构

当返回 

UPSTREAM_ALL_FAILED
UPSTREAM_ALL_FAILED
时，响应会包含 
retry_history
retry_history
数组，按尝试顺序列出每个上游端点的失败信息。

{ "error": { "code": "UPSTREAM_ALL_FAILED", "message": "[G2] Upstream failed. path=/v1/chat/completions, requestId=req-abc, virtualKey=vk-xxx, tenantId=123", "source": "upstream", "retry_history": [ { "endpoint_id": 101, "slug_name": "aliyun-bailian/qwen3.7-max", "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key_alias": "prod-bailian-key", "provider": "aliyun-bailian", "model": "qwen3.7-max", "status": 429, "body": "{\"message\":\"Too many requests\"}" }, { "endpoint_id": 202, "slug_name": "volcengine/doubao-seed-2.0-pro", "base_url": "https://ark.cn-beijing.volces.com/api/v3", "api_key_alias": "prod-ark-key", "provider": "volcengine", "model": "doubao-seed-2.0-pro", "status": 500, "body": "{\"error\":{\"message\":\"Internal server error\"}}" } ] } }

字段说明：

字段说明
endpoint_id
endpoint_id
端点的内部标识。
slug_name
slug_name
端点对应的供应商和模型标识。
base_url
base_url
本次尝试使用的上游基础 URL。
api_key_alias
api_key_alias
本次调用所用 API Key 的别名。
provider
provider
供应商标识。
model
model
本次尝试使用的模型标识。
status
status
上游返回的 HTTP 状态码。
body
body
上游返回的原始错误报文，可能会被截断。

排查时，优先关注：

  • provider
    provider
    ：失败发生在哪个供应商。
  • model
    model
    ：是否是预期模型。
  • status
    status
    ：是否为限流、鉴权、参数错误或服务异常。
  • body
    body
    ：上游原始错误信息。

七、典型排查场景

1. API Key 缺失或无效

表现：

  • HTTP 状态为 
    401
    401
    。
  • code
    code
    为 
    GATEWAY_MISSING_VIRTUAL_KEY
    GATEWAY_MISSING_VIRTUAL_KEY
    、
    GATEWAY_INVALID_VIRTUAL_KEY
    GATEWAY_INVALID_VIRTUAL_KEY
    或 
    GATEWAY_VIRTUAL_KEY_DISABLED
    GATEWAY_VIRTUAL_KEY_DISABLED
    。

处理：

  • 检查请求头是否包含 
    Authorization: Bearer <API_KEY>
    Authorization: Bearer <API_KEY>
    。
  • 确认 API Key 来自 AI Gateway，而不是云厂商原始 Key。
  • 到 
    API KEY 管理
    API KEY 管理
    页面确认 Key 是否启用。

2. 模型名称错误

表现：

  • HTTP 状态为 
    400
    400
    。
  • code
    code
    可能为 
    GATEWAY_MODEL_NOT_RESOLVED
    GATEWAY_MODEL_NOT_RESOLVED
    或 
    GATEWAY_NO_UPSTREAM_CANDIDATES
    GATEWAY_NO_UPSTREAM_CANDIDATES
    。

处理：

  • 到 
    模型广场
    模型广场
    复制模型详情页中的模型名称。
  • 不要自行猜测云厂商模型 ID。
  • 检查接口类型是否与模型能力匹配，例如不要用图片生成接口调用文本模型。

3. BYOK 配置错误

表现：

  • 默认模式或指定供应商模式下，可能先尝试 BYOK 后回退到平台内置供应商。
  • 仅 BYOK 模式下，所有 BYOK 端点失败后会直接报错。

处理：

  • 到 
    BYOK
    BYOK
    页面检查供应商 Key 是否有效。
  • 确认云厂商侧已开通对应模型。
  • 如果业务允许回退，可从 
    仅 BYOK
    仅 BYOK
    切换为默认或指定供应商模式。

4. 上游限流

表现：

  • HTTP 状态可能为 
    429
    429
    或最终返回 
    UPSTREAM_ALL_FAILED
    UPSTREAM_ALL_FAILED
    。
  • retry_history.status
    retry_history.status
    中出现 
    429
    429
    。

处理：

  • 降低并发。
  • 使用指数退避重试。
  • 调整路由策略，增加可用供应商。
  • 联系管理员提高供应商限额。

5. 异步任务重复创建

表现：

  • 视频、图片、3D 生成任务重复提交，导致重复计费或重复结果。

处理：

  • 业务侧增加幂等键。
  • 用户重复点击时复用已有任务。
  • 对创建任务接口不要盲目自动重试。

八、排查清单

遇到错误时，可按以下顺序处理：

  1. 读取 
    error.code
    error.code
    ，确定错误类别。
  2. 查看 
    source
    source
    ，判断问题发生在网关还是上游。
  3. 如果是 
    gateway
    gateway
    ，检查 API Key、配额、模型名称、接口路径和路由策略。
  4. 如果是 
    upstream
    upstream
    ，查看 
    retry_history
    retry_history
    中每次尝试的 
    provider
    provider
    、
    model
    model
    、
    status
    status
    和 
    body
    body
    。
  5. 根据 HTTP 状态判断是否可以重试。
  6. 如果需要联系支持，请提供 
    requestId
    requestId
    、API Key 名称、模型名称、请求时间和错误响应。
DeepSeek Anthropic Messages 兼容调用
最佳实践
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.
联系我们
预约咨询
微信咨询
电话咨询
邮件咨询