API 报错排查：401、403、429、502 错误码说明

88API 接口返回 401、403、404、429、5xx 等错误时的含义和处理方法，包括令牌无效、余额不足、模型不可用、请求过快和 Claude Code、Codex 的常见报错。

调用失败时，接口会返回 HTTP 状态码和一段 JSON，错误原因写在 error.message 里：

{
  "error": {
    "code": "",
    "message": "无效的令牌 (request id: 2026101605444223...)",
    "type": "new_api_error"
  }
}

message 末尾的 request id 是这次请求的编号，联系客服时一起提供。控制台的「使用日志」页面也会记录失败请求的时间、模型和错误信息。排查时先看状态码，再看 message。

速查表

状态码	含义	先做什么
400	请求内容或参数不被模型接受	按报错信息修改参数、提示词或图片
401	令牌无效	检查 API Key 是否填对、是否已删除
403	令牌不可用、余额不足或没有权限	检查余额、令牌状态、令牌的分组和模型限制
404	地址或模型不存在	检查接口地址是否多了 `/v1`，模型名是否在当前分组可用
429	请求过快或模型繁忙	降低频率，稍后重试
500、502、503、504、524	模型服务暂时不可用或超时	稍后重试；持续失败时换分组或换模型

401：令牌无效

常见信息：无效的令牌、invalid token。

API Key 复制不完整，或前后带了空格、换行。
令牌已在控制台删除。到 API 令牌页面重新创建或复制。
Claude Code：同时设置了旧的 ANTHROPIC_API_KEY。它的优先级高于 ANTHROPIC_AUTH_TOKEN，请删除它，只保留 ANTHROPIC_AUTH_TOKEN。
请求头写法：OpenAI 格式用 Authorization: Bearer sk-...；Anthropic 格式用 x-api-key: sk-...。

403：令牌不可用、余额不足或没有权限

余额或额度不足

常见信息：用户额度不足、预扣费额度失败, 用户剩余额度: …, 需要预扣费额度: …。

账户余额不够本次请求的预扣费。请到钱包充值。
账户有余额但仍提示不足：令牌可以单独设置额度上限，检查该令牌的剩余额度。
Claude Code 会把这类 403 显示成「认证失败」或「API Error 403」，处理方法相同。

令牌状态不可用

常见信息：该令牌状态不可用。

令牌被禁用、已过期或令牌额度已用完。在 API 令牌页面启用令牌、修改过期时间或调整额度。

没有分组或模型权限

常见信息：无权访问 … 分组、API Key 所属专属分组不再允许当前用户使用、该令牌无权访问模型 …。

令牌绑定的分组当前账户不能使用：编辑令牌，换成模型广场里可用的分组。
令牌设置了模型限制：在令牌设置里放开对应模型，或者换一个令牌。

当前分组不支持这个接口

常见信息：This group does not allow /v1/messages dispatch。

所选分组不支持这种协议的接口（例如用只支持 OpenAI 格式的分组去调用 Anthropic 的 /v1/messages）。Claude Code 请使用 Claude 分组的令牌；其他客户端按模型广场里该模型支持的接口类型调用。

404：地址或模型不存在

地址多了或少了 /v1

常见信息：Invalid URL、404 page not found。

Claude Code 的 ANTHROPIC_BASE_URL 填 https://api.88api.ai，不要加 /v1（Claude Code 会自己拼 /v1/messages，写成 .../v1 会变成 /v1/v1/messages）。
Codex 的 base_url 填 https://api.88api.ai/v1，必须带 /v1。
大多数 OpenAI 兼容应用填 https://api.88api.ai/v1。各应用的写法见应用接入教程。

模型在当前分组不可用

常见信息：分组 … 下模型 … 无可用渠道、Model "…" is not supported by any configured account in this group、model not found。

模型名写错，或者带了多余的前缀、后缀。在个人设置或模型广场里复制准确的模型名。
该模型不在令牌所选的分组里。在模型广场查看模型支持哪些分组，然后修改令牌的分组。

400：请求内容或参数不被接受

报错信息（示例）	原因和处理
`输入内容超过模型上下文限制`、`Input exceeds the context limit`	对话太长。删减历史记录或开新会话；Claude Code 里可以用 `/compact` 压缩上下文
`请求中包含该模型不支持的参数（如 presence_penalty / frequency_penalty）`	去掉报错里提到的参数
`该模型是生图模型，不能通过对话接口调用`	生图请用 `/v1/images/generations`，改图用 `/v1/images/edits`，见图片接口
`请使用 Gemini 原生接口调用`	该模型只支持 Gemini 原生格式，见 Gemini 接口
`the selected model cannot disable reasoning`、`不支持关闭深度思考`	这个模型必须开启思考，去掉关闭思考的参数（或把思考类型设为 enabled）
`requires adaptive thinking`	该 Claude 模型要求自适应思考：去掉 `thinking` 参数，或按报错提示改成 `type=adaptive`
`当前输入触发平台内容安全规则`、`未通过内容安全审核`、`可能违反了…内容政策`	提示词或参考图被安全审核拦截，修改内容后再试
`Failed to download multimodal content`、`mime type is not supported`	图片地址无法访问或格式不支持。换成公网可访问的 PNG、JPEG、WebP 图片，或改用 base64

429：请求过快或繁忙

账户请求频率超限

常见信息：您的请求频率过快；当前用户组 … 分钟内最多允许 … 次成功请求。

默认限制为 60 RPM（每分钟请求数）。降低并发或在客户端加重试间隔；确实需要更高的频率，可以联系客服申请提高。

模型繁忙

常见信息：Upstream rate limit exceeded、service error, please try again later、Concurrency limit exceeded。

模型当前请求量大。稍等几秒重试；需要稳定可以在模型广场换一个分组。

500、502、503、504、524：服务暂时不可用或超时

常见信息：Upstream service temporarily unavailable、Service temporarily unavailable. Please retry.、系统过载，请稍后重试、模型请求失败，请稍后重试或更换模型、bad response status code 504。

这类错误多是模型服务一时繁忙或网络波动，通常重试即可恢复。建议客户端按 1 秒、2 秒、4 秒逐步加大间隔重试。
同一个模型持续失败时，换一个分组或换一个模型。
524、504 多发生在生成时间很长的请求上：对话请求请开启流式输出（stream: true）；生图、视频请用异步任务接口轮询结果。

仍然解决不了

在使用日志里找到失败的那条记录，把**请求时间、模型名、状态码和完整报错信息（含 request id）**发给在线客服。不要发送你的完整 API Key。

错误码与常见报错

速查表