错误码大全

先看结论

使用 OpenAI 兼容接口时，大多数报错都可以先按 HTTP 状态码判断。建议先看返回的 status，再看响应体里的 error.message、error.type 或 error.code。

400：请求格式或参数错误

400 Bad Request 表示请求还没有进入正常计费流程，常见原因是 JSON、接口或参数写错。

常见表现：

• JSON 语法错误，例如少了逗号、引号或右括号。
• Content-Type 不是 application/json。
• 调错接口，例如把聊天模型发到图片接口。
• 必填字段缺失，例如没有传 model 或 messages。
• 参数类型错误，例如把数字写成字符串，或把数组写成对象。

处理建议：

• 先复制文档里的最小示例跑通，再逐项加回自己的参数。
• 确认 /v1/chat/completions、/v1/responses、/v1/images/generations 等路径和模型能力匹配。
• 如果使用客户端软件，先删除高级参数，只保留 Base URL、API Key 和模型名测试。

401：API Key 无效或鉴权头错误

OpenAI 兼容接口必须带 Authorization 请求头：

Authorization: Bearer sk-xxx

常见原因：

• 少写 Bearer。
• Bearer 和 Key 中间没有空格。
• Key 前后复制进了空格、换行或中文符号。
• 把 Key 填到了模型名、组织 ID、代理地址等位置。
• 令牌已删除、已重置、被禁用，或复制的是旧 Key。

处理建议：

• 在”API密钥“重新复制 Key。
• 客户端里只保留一个 API Key，避免新旧 Key 混用。
• 不要把完整 API Key 发给客服或贴到公开截图中。

402：余额不足或额度不足

402 Payment Required 通常表示账户余额不足、令牌额度不足，或本次请求预计消耗超过可用余额。

常见原因：

• 主账户余额为 0 或余额不足。
• 令牌设置了额度上限，已经用完。
• 请求上下文很长、图片/视频任务单价较高，导致单次预估消耗超过余额。
• 刚充值后页面或客户端仍使用旧状态，需要刷新后再试。

处理建议：

1. 打开钱包充值。
2. 回到控制台确认余额已经到账。
3. 检查当前令牌是否设置了额度上限。
4. 缩短上下文、降低输出长度，或换用更低倍率模型后重试。

403：令牌无权限或分组不支持模型

403 Forbidden 最常见的原因是“令牌分组”和“模型”不匹配。比如令牌在 default 分组，但调用了只在 Claude、Gemini、生图或视频分组里的模型。

常见表现：

• model not allowed
• group not support
• forbidden
• You are not allowed to use this model

处理建议：

1. 到”API密钥“找到正在使用的令牌。
2. 查看令牌所属分组，以及是否有模型白名单、额度限制、过期时间。
3. 确认当前 API 密钥具有该模型的调用权限，然后重新发起请求。
4. 如果只是临时测试，也可以换成当前分组支持的模型。

404：接口路径或模型名不存在

404 Not Found 通常不是网络问题，而是路径或模型名没有匹配上。

常见原因：

• Base URL 少了 /v1，或多写了一层路径。
• 使用了模型展示名，而不是模型 ID。
• 模型名手打错误、大小写错误，或末尾带空格。
• 模型已经下架或换名。
• 客户端把 base_url 和 endpoint 拼接重复，例如变成 /v1/v1/chat/completions。

处理建议：

• Base URL 填 https://api.cofinapi.top/v1。
• 模型名从主站价格页复制，不要手打。
• 用 curl -i 单独测试一次，排除客户端拼接路径的问题。

408 / 504：请求或上游响应超时

超时通常发生在长上下文、长输出、图片/视频、联网检索或上游繁忙时。

处理建议：

• 缩短输入内容，删除无关历史对话。
• 降低 max_tokens 或客户端里的最大输出长度。
• 图片、文件、视频任务尽量减少单次上传内容。
• 使用指数退避重试，例如等待 2s、4s、8s。
• 如果同一模型持续超时，临时切换同类模型或稍后再试。

413：请求体过大

413 Payload Too Large 表示请求内容超过服务器或上游可接受范围。

常见原因：

• 一次性发送太长的历史记录。
• 图片 base64 过大。
• 文件、音频或视频参数超出接口限制。
• 客户端把完整日志、网页源码或大型文件直接塞进 prompt。

处理建议：

• 对长文档先摘要，再分段提问。
• 图片尽量使用压缩后的 URL 或较小尺寸。
• 避免在同一轮里附带过多历史消息。
• 对批量任务做队列拆分，不要一次塞入全部内容。

422：参数不符合模型要求

422 Unprocessable Entity 表示请求体能解析，但某些字段不被当前模型或接口接受。

常见原因：

• 当前模型不支持 tools、response_format、图片输入或音频输入。
• messages 结构不符合要求，例如图片内容格式写错。
• 传了模型不支持的尺寸、比例、时长、采样参数。
• 使用 Responses API 参数调用 Chat Completions API，或反过来。

处理建议：

• 先去掉 tools、response_format、temperature、top_p 等高级参数，确认基础对话能跑通。
• 按模型所属文档选择接口，例如聊天、图像、视频不要混用。
• 如果是客户端自动带的参数，在客户端里关闭不兼容功能后重试。

429：限流或并发过高

429 Too Many Requests 表示请求速度、并发数或队列压力超过了当前限制。

常见原因：

• 多个客户端共用同一个令牌。
• 程序没有限速，短时间内集中发请求。
• 同时跑大量长任务、图片任务或视频任务。
• 上游通道本身暂时拥堵。

处理建议：

• 降低并发，把批量任务改成队列。
• 给不同客户端创建不同令牌，方便定位是谁打满了额度。
• 读取响应头里的 Retry-After，如果有就按它等待。
• 没有 Retry-After 时，按 2s、4s、8s、16s 退避重试。

Node.js 重试示例：

async function withRetry(fn) {
  for (let i = 0; i < 4; i++) {
    try {
      return await fn();
    } catch (error) {
      const status = error.status || error.response?.status;
      if (![408, 429, 500, 502, 503, 504].includes(status) || i === 3) {
        throw error;
      }
      const delayMs = 1000 * 2 ** i;
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }
}

500 / 502 / 503：服务或上游临时异常

5xx 表示请求已经到达服务端，但中转服务或上游模型通道返回了异常。它通常是临时问题，可以重试，但也要避免无限重试。

处理建议：

• 等 10 到 30 秒后重试一次。
• 降低并发和单次请求长度。
• 切换同类型模型或同分组里的其他模型。
• 如果只在某个模型上出现，优先记录模型名和时间点。
• 如果连续多次出现，再联系支持。

哪些错误可以自动重试

适合自动重试：

• 408
• 429
• 500
• 502
• 503
• 504

不适合自动重试：

• 400
• 401
• 402
• 403
• 404
• 413
• 422

推荐重试规则：

1. 最多重试 3 到 4 次。
2. 每次间隔递增，例如 2s、4s、8s、16s。
3. 只重试幂等或可接受重复执行的任务。
4. 对图片、视频等高成本任务，确认失败没有产生计费后再批量重试。

联系支持时请带上这些信息

为了更快定位问题，请尽量提供：

• 报错发生时间，最好精确到分钟。
• 使用的 Base URL。
• 调用的接口路径，例如 /v1/chat/completions。
• 模型名。
• HTTP 状态码。
• 完整错误信息或截图。
• 客户端名称，例如 Cherry Studio、Cursor、Claude Code、Chatbox、Python SDK、Node.js SDK。
• 令牌名称或令牌后 4 位，不要发送完整 API Key。
• 如果有请求 ID、Trace ID 或响应头，也一并提供。