Skip to content

错误与重试 ​

错误格式 ​

错误体跟随你调用的协议:OpenAI 接口返回 OpenAI 格式,Claude 接口返回 Claude 格式,Gemini 接口返回 Gemini 格式,官方 SDK 的错误处理可以直接使用。

OpenAI 格式:

json
{
  "error": {
    "message": "Invalid token (request id: 2026111605183113110223...)",
    "type": "new_api_error",
    "code": ""
  }
}

Claude 格式:

json
{"type": "error", "error": {"type": "...", "message": "..."}}

Gemini 格式:

json
{"error": {"code": 503, "message": "The service is temporarily unavailable. Try again later.", "status": "UNAVAILABLE"}}

错误信息里的 request id 用于排查,联系客服时请一并提供。

常见状态码 ​

状态码常见原因怎么处理
400参数不合法、JSON 格式错误、图片尺寸不符合要求按错误信息修改,不要重试
401令牌无效、已删除、已过期,或没有带令牌(Invalid token)检查令牌是否完整、是否带了 Bearer 前缀、请求头名称是否正确
403余额或令牌额度不足;令牌分组已不可用充值或调整令牌额度;在控制台把令牌换到可用分组
404接口路径不存在;上游没有这个模型核对路径和模型名
413请求体超过 256 MB压缩图片或改用文件上传
429请求过于频繁或并发已满等待后重试
500、502上游出错稍后重试
503暂时没有可用的服务;模型名写错,或令牌分组里没有这个模型也会返回 503先在 模型广场 核对模型名和分组;确认无误再重试
504等待上游超时用流式输出,或拆小任务后重试

返回了一个网页?

请求返回 200 但内容是 HTML,说明路径少了 /v1,请求落到了网站首页。OpenAI SDK 的 Base URL 要填 https://api.codingrouter.ai/v1。

重试建议 ​

  • 400、401、403、404、413 不要重试,结果不会变。
  • 429 和 5xx 可以重试,用指数退避:等 1 秒、2 秒、4 秒……最多重试 3 到 5 次。
  • 连续出现 503 时,先排除模型名和分组问题。
  • 生成时间长的请求(长文本、推理模型、图像),把客户端超时设到 300 秒以上,或使用流式输出。

还是不行? ​

把以下信息发给客服:

  • 请求时间(精确到分钟)
  • 模型名和接口路径
  • 完整的错误信息(包括 request id)
  • 令牌名称(不要发送令牌本身)