错误与重试
错误格式
错误体跟随你调用的协议: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) - 令牌名称(不要发送令牌本身)
