错误码

调用失败时,平台返回非 2xx 的 HTTP 状态码和一个 JSON 错误体。排查顺序:

  1. 看 HTTP 状态码,确定错误类别和要不要重试,见 状态码速查。
  2. 看 error.code 和 error.message,在对应状态码小节里定位具体原因。
  3. 按「处理方式」修正,仍无法解决时带上请求 ID 联系客服。
JSON
{
  "error": {
    "message": "令牌无效或已过期,请检查令牌",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_token"
  }
}

程序判断请依据 HTTP 状态码,必要时再结合 error.code。message 是给人看的中文说明,会随版本调整,不要做精确匹配;部分 message 末尾会带一个控制台链接,处理时到控制台对应页面(如「API Keys」页)操作即可。

请求 ID:每个响应都带响应头 X-Oneapi-Request-Id,部分错误的 message 末尾也会附带 (请求ID:…)。联系客服时请提供该值。

状态码速查

HTTP 类别 能否重试 先检查
400 请求内容有误 否 请求体、参数、输入内容 → 400
401 鉴权失败 否 API Key 与请求头 → 401
402 额度不足 否 API Key 额度、账户余额、套餐 → 402
403 无权限 否 API Key 的 IP 白名单、模型限制、分组 → 403
404 路径或模型不存在 否 Base URL、路径、模型名 → 404
413 请求体过大 否 图片、附件、输入长度 → 413
422 不支持的调用方式 否 接口与参数组合 → 422
429 频率、并发或用量受限 是,退避 请求频率与并发 → 429
500 / 502 / 503 / 504 / 529 服务端或模型服务商异常 是,退避 → 5xx
501 接口未提供 否 → 501

少数情况下,模型服务商侧的账号、鉴权或额度问题也会以 401 / 402 / 403 返回,与你的 API Key 无关,识别方式见 模型服务商侧问题。

错误响应格式

错误体的结构由请求路径决定,与实际调用的是哪家模型无关。

OpenAI 格式

默认格式。除 /v1/messages、/v1/messages/count_tokens 外的接口(包括 Chat、Responses、图片、向量、/v1beta Gemini 原生接口)都返回上文示例中的格式:

字段 说明
error.message 可读的错误说明
error.type 错误类别。平台自身拦截的错误为 new_api_error;模型服务商返回的错误为 invalid_request_error、authentication_error、permission_error、rate_limit_error、quota_error、overloaded_error、upstream_error 等
error.code 错误码,见下文各节;部分错误为空字符串
error.param 出错的参数名,多数情况为空

Gemini 原生接口(/v1beta/models/...)出错时返回的也是 OpenAI 格式,而不是 Google 的 {"error": {"code", "status"}} 格式。使用 Google GenAI SDK 时请按 HTTP 状态码处理异常。

视频、Suno、Midjourney 等任务类接口的错误体结构不同,见各自文档(如 视频生成概述、Midjourney)。

Anthropic 格式

/v1/messages 与 /v1/messages/count_tokens 返回 Anthropic 风格:

JSON
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "令牌无效或已过期,请检查令牌"
  },
  "request_id": "2026110912000012345678"
}

API Key 鉴权与额度、IP / 模型 / 分组权限、请求频率限制这类在调用模型前就被拦截的错误,error.type 按状态码取值,响应体带 request_id(同时有响应头 request-id):

HTTP error.type
400 / 422 invalid_request_error
401 authentication_error
402 billing_error
403 permission_error
429 rate_limit_error
其他 api_error

其中 400、401、402、403、404、413、422 还会带响应头 x-should-retry: false,Anthropic SDK 据此不再自动重试。

其他错误(如账户余额不足、模型服务商返回的错误)不带 request_id,error.type 可能是 overloaded_error、rate_limit_error、new_api_error 等,请以 HTTP 状态码为准。

流式请求中的错误

以 stream: true 发起、且已经开始返回数据后才出错时,HTTP 状态码已经是 200,错误会作为一条 SSE 事件下发。流式客户端需要在解析每个事件时检查是否为错误事件。

Chat Completions 等 OpenAI 接口:一条错误 data: 后紧跟结束标志

CODE
data: {"error":{"message":"服务异常,请稍后重试","type":"new_api_error","param":"","code":"bad_response_status_code"}}

data: [DONE]

Responses:

CODE
event: error
data: {"type":"error","code":"rate_limit","message":"上游限流,请稍后重试","param":""}

Anthropic Messages:

CODE
event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"上游负载过高,请稍后重试"}}

如果错误发生在开始返回数据之前,则按非流式方式返回对应状态码和错误体。

按状态码排查

下表「典型 message」为错误信息原文(… 表示省略的数值或链接)。

400 请求内容有误

code 典型 message 原因 处理方式
— 请求体格式错误,请检查 JSON 请求体不是合法 JSON 校验 JSON;确认 Content-Type: application/json
bad_request_body 请求体格式错误,请检查 JSON 请求体能解析,但字段类型与接口不符 对照接口文档检查字段类型
bad_request_body 或 — 请求体格式错误,请检查 multipart/form-data 上传类接口的表单格式错误 检查字段名与文件字段
— 未指定模型名称,模型名称不能为空 未传 model 补充 model
invalid_request 请求参数错误 / xxx 参数需大于等于 N 等 参数缺失或取值越界 按 message 修正参数
sensitive_words_detected 请求包含敏感内容,请修改后重试 输入命中平台内容过滤 修改输入内容
prompt_blocked 请求内容可能触发安全策略而被拦截,请修改内容后重试 被模型服务商的安全策略拦截 修改输入内容
— 提示词太长,当前上下文已达到上限,建议在 Claude Code 中执行 /compact 压缩当前会话,或缩短输入后重试 超出模型上下文长度 缩短输入或清理历史消息;Claude Code 中执行 /compact
model_not_found 模型 xxx 暂时不可用 模型服务商不再提供该模型 用 GET /v1/models 换一个可用模型

401 鉴权失败

code 典型 message 原因 处理方式
invalid_token 令牌无效或已过期,请检查令牌:… 未带 API Key,或 API Key 不存在、已删除、已禁用、已过期 检查请求头格式与 API Key 状态,见 获取与配置 API Key

402 额度不足

code 典型 message 原因 处理方式
token_quota_exhausted 该令牌额度不足,令牌剩余额度:…。请更换令牌或调整令牌额度:… API Key 设置的可用额度已用完 在「API Keys」页调高额度或改为不限额度
pre_consume_token_quota_failed 该令牌额度不足,可用余额约 …,本次请求预扣费预计至少 …。请更换令牌或调整令牌额度:… API Key 剩余额度不够本次请求预扣 同上;或调小 max_tokens
insufficient_user_quota 余额不足,账户可用余额约 …,本次请求预扣费预计至少 …。请前往充值:… 账户余额不足 在控制台充值;或调小 max_tokens
insufficient_user_quota 套餐额度已用完,请续购 API Key 绑定的套餐已用完,且「套餐用完后」设为停止调用 续购套餐,或把 API Key 改为「改用账户余额」

预扣费:请求开始前,平台按输入长度与 max_tokens 预扣一部分额度,请求结束后按实际用量多退少补。余额接近不足时,调小 max_tokens 可能让请求通过。

403 无权限

code 典型 message 原因 处理方式
— 您的 IP 不在令牌允许访问的列表中 API Key 设置了 IP 白名单,当前出口 IP 不在其中 把公网出口 IP 加入白名单,或清空白名单
— 该令牌无权访问模型 xxx,请在控制台调整令牌权限:… API Key 开启了模型限制,请求的模型不在列表中 在 API Key 的「模型限制」中添加该模型
— 令牌分组 xxx 已被禁用 API Key 所选分组不在账号可用范围内 编辑 API Key,换一个可用分组
— 分组 xxx 已被弃用 API Key 所选分组已下线 编辑 API Key,换一个可用分组
— 该模型暂不提供服务 平台已停止提供该模型 换模型
— 用户已被封禁 账号被停用 联系客服
— 组织已被禁用,无法发起新请求 / 组织成员状态不可用 企业 API Key 所属组织或成员被停用 联系你所在组织的管理员
— 普通用户不支持指定渠道 API Key 后面追加了 -数字 后缀 使用控制台复制的完整 API Key,不要追加后缀

404 路径或模型不存在

code 典型 message 原因 处理方式
— Invalid URL (POST /v1/xxx) 路径不存在 检查 Base URL 与路径,见 Base URL 总览
model_not_found 模型 xxx 暂时不可用 模型名写错,或该模型当前没有可用服务 用 GET /v1/models 核对模型名;确认无误则稍后重试
model_not_found 当前分组不支持模型 xxx,请切换分组或在控制台调整令牌分组。 该模型不在 API Key 所在分组 编辑 API Key 换分组

413 请求体过大

code 典型 message 原因 处理方式
— 请求内容过大,已超出单次请求大小限制。请减少图片/附件或缩短输入,必要时分段发送。 请求体超出大小限制 压缩图片、减少附件、缩短输入

422 不支持的调用方式

code 典型 message 原因 处理方式
— 该接口或请求参数组合暂不支持(接口:…),请调整调用方式或联系管理员 该模型不支持此接口或参数组合 换接口(参考 模型列表 的 supported_endpoint_types)或去掉不支持的参数
unsupported_request 请求体不符合规范(Unsupported request body),请使用 /clear 重新开始对话 模型服务商拒绝了请求体结构 精简请求体;Claude Code 中执行 /clear

429 频率、并发或用量受限

code 典型 message 原因 处理方式
— 您已达到请求数限制:N分钟内最多请求M次 超出请求频率限制 降低频率,按退避策略重试
— 您已达到总请求数限制:N分钟内最多请求M次,包括失败次数,请检查您的请求是否正确 请求总数(含失败请求)超限 检查是否有大量失败请求在循环重试
— 该模型并发已达上限,请稍后再试 你对该模型的并发请求数超限 降低并发
— 该模型当前繁忙,请稍后再试 该模型整体繁忙 稍后重试
— 该模型今日调用次数已用完 / 该模型今日额度已用完 该模型的每日次数或额度已满 次日再试或换模型
rate_limit 上游限流,请稍后重试 模型服务商限流 退避重试
— 请求过于频繁,请稍后再试 模型服务商限流 退避重试
— (空响应体) 同一来源的请求过于频繁 降低请求频率

5xx 服务端或模型服务商异常

HTTP code 典型 message 原因 处理方式
503 — 服务暂不可用,请稍后重试 平台临时故障 稍后重试
503 — 渠道配置异常,请联系管理员 平台侧服务配置问题 联系客服并提供请求 ID
500 model_price_error 模型 xxx 未配置定价,请联系管理员设置 该模型暂未开放计费 换模型或联系客服
502 / 5xx bad_response_status_code 等 服务异常,请稍后重试 / 请求失败,请稍后重试 模型服务商返回异常 稍后重试
502 empty_response 服务暂时无响应,请稍后重试 模型服务商返回空内容 重试
504 channel:response_time_exceeded 服务响应超时,请稍后重试 模型服务商响应超时 重试;长输出建议使用流式
529 overloaded 上游负载过高,请稍后重试 模型服务商过载 退避重试

501 接口未提供

code 典型 message 原因 处理方式
api_not_implemented 接口暂不支持 调用了平台未提供的接口(如 /v1/files) 不要调用该接口

模型服务商侧问题

以下错误由模型服务商侧的账号或权限问题引起,与你的 API Key 无关,无需修改 API Key 配置:

HTTP code 典型 message 处理方式
402 insufficient_quota 当前模型暂时不可用,请稍后重试或联系管理员 稍后重试、换模型,或联系客服
403 permission_denied 上游渠道账号或模型权限不足,请联系管理员 同上
401 authentication_error 上游鉴权失败… 同上

重试建议

  • 可以重试:429、500、502、503、504、529。使用指数退避(如 1s、2s、4s),并设置最大重试次数。
  • 不要重试:400、401、402、403、404、413、422、501。修正请求或账号状态后再发。
  • 平台会自动重试模型服务商的临时故障,客户端无需高频重试。

相关文档