错误码
调用失败时,平台返回非 2xx 的 HTTP 状态码和一个 JSON 错误体。排查顺序:
- 看 HTTP 状态码,确定错误类别和要不要重试,见 状态码速查。
- 看
error.code和error.message,在对应状态码小节里定位具体原因。 - 按「处理方式」修正,仍无法解决时带上请求 ID 联系客服。
{
"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 风格:
{
"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: 后紧跟结束标志
data: {"error":{"message":"服务异常,请稍后重试","type":"new_api_error","param":"","code":"bad_response_status_code"}}
data: [DONE]
Responses:
event: error
data: {"type":"error","code":"rate_limit","message":"上游限流,请稍后重试","param":""}
Anthropic Messages:
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。修正请求或账号状态后再发。 - 平台会自动重试模型服务商的临时故障,客户端无需高频重试。