错误码与排查

错误响应格式

OpenAI 兼容接口出错时返回如下 JSON，message 末尾附带 request id，联系客服时请一并提供：

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

Claude 原生接口返回 {"type": "error", "error": {"type": "...", "message": "..."}} 格式，Gemini 原生接口返回 {"error": {"code": ..., "message": "...", "status": "..."}} 格式。

HTTP 状态码

状态码	含义	常见原因与处理
400	请求参数错误	参数名或取值不被模型支持（如推理模型传了 temperature、max_tokens），按提示修改
401	认证失败	令牌错误、已删除、已禁用、已过期或额度用完
403	无权访问	令牌开启了模型限制或 IP 限制；账户余额不足
404	地址不存在	Base URL 或路径写错，常见于多写或少写了 /v1
413	请求体过大	图片、文件过大，压缩后重试或改用 URL
429	请求过多	触发限流或上游繁忙，稍后重试，建议使用指数退避
500	服务内部错误	偶发错误，稍后重试；持续出现请联系客服
502 / 503	上游不可用	上游渠道暂时故障或该分组暂无可用渠道，稍后重试或切换分组
504 / 524	超时	非流式请求耗时过长；经 Cloudflare 线路时超过约 100 秒会返回 524，改用流式或主站点

常见错误提示

提示	原因	解决方法
无效的令牌	密钥不正确或已被删除	检查是否复制完整（sk- 开头）、是否有多余空格
该令牌已过期 / 该令牌额度已用尽	令牌到期或达到额度上限	在控制台修改过期时间或调高额度
当前分组 xxx 下对于模型 xxx 无可用渠道	令牌分组没有这个模型，或模型名拼写错误	到 模型列表 核对模型名和所在分组，修改令牌分组
该令牌无权访问模型 xxx	令牌开启了模型限制	编辑令牌，把模型加入允许列表或关闭限制
用户额度不足 / 预扣费额度失败	账户余额不足	充值 后重试
您已达到请求数限制	触发请求频率限制	降低并发或稍后重试
invalid character '<' looking for beginning of value	请求落到了网页而不是接口上	检查 Base URL 写法，见 接口地址与线路
Unsupported parameter: 'max_tokens'	推理模型不支持该参数	改用 max_completion_tokens
Unsupported value: 'temperature'	推理模型不支持自定义采样参数	删除 temperature、top_p 等参数

排查清单

1. 地址：Base URL 是否与客户端要求一致（带不带 /v1）？换一条线路是否正常？
2. 密钥：令牌是否启用、未过期、有额度？账户余额是否充足？
3. 模型：模型名是否与 模型列表 完全一致？令牌分组是否包含该模型？
4. 参数：先用最简单的请求（只有 model 和 messages）确认能通，再逐个加回其他参数。
5. 超时：长任务是否开启了流式？是否经过了 Cloudflare 线路？
6. 日志：在 使用日志 中查看请求是否到达、是否扣费。

仍无法解决时，请把完整错误信息（含 request id）、请求时间、模型名和令牌分组发给客服。