错误码

错误统一返回 JSON：

{
  "error": {
    "message": "人类可读的原因",
    "type": "错误类型",
    "code": "可选的具体错误码"
  }
}

HTTP 状态码

状态码	含义	常见原因	处理
400	请求格式错误	JSON 不合法、缺少 model、参数类型不对	对照接口文档修正请求体
401	未鉴权	没带令牌、Key 拼错、令牌被禁用或过期	检查 Authorization 头与令牌状态
402	余额不足	额度耗尽	充值，或换用更低倍率的分组
403	无权限	令牌不在该分组、模型不在白名单、IP 不在白名单	检查令牌的模型 / 分组 / IP 限制
404	找不到	路径写错、模型不存在	核对端点与模型名
429	触发限流	RPM / TPM / RPD 超限，或上游限流	指数退避重试，见速率限制
500	服务内部错误	上游返回异常、渠道配置问题	可重试；持续出现请反馈
502 / 503	上游不可用	渠道全部失败、无可用渠道	换分组或稍后重试

排查顺序

1. 用 curl 复现，确认不是 SDK 的问题。
2. 用 GET /v1/models 确认令牌能看到目标模型。
3. 查看响应体的 error.message，它通常直接说明原因。
4. 仍无法解决时，把请求时间、模型名、令牌名、响应体一起反馈（不要贴完整 Key）。