错误码

HTTP 状态码、错误响应结构，以及网关自有的 code 取值。

错误响应结构

OpenAI 协议返回 error 对象：

{
  "error": {
    "message": "错误描述",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

Anthropic 协议返回：

{
  "type": "error",
  "error": {
    "type": "insufficient_user_quota",
    "message": "错误描述"
  }
}

message 会对敏感信息做脱敏，所以上游返回的原始细节可能不完整。完整的错误分类与状态码在控制台的错误记录里查询。

HTTP 状态码

状态码	含义	处理
`400`	请求体不合法，或参数超出允许范围	按 `message` 修正请求，重试无用
`401`	密钥无效、已过期或已被禁用	检查密钥，必要时新建一把
`403`	出口 IP 不在密钥的允许列表中，或账号被禁用	调整 IP 允许列表，或联系管理员
`404`	路径不存在，或模型不在密钥所属分组内	核对 Base URL 与模型名
`429`	触发限流	按 `Retry-After` 或响应体提示退避重试
`500`	网关内部错误	可重试
`502` / `503`	上游异常且无可用账号	可重试

`type` 取值

值	来源
`new_api_error`	网关自身产生的错误
`openai_error`	透传自 OpenAI 协议的上游
`claude_error`	透传自 Anthropic 协议的上游
`gemini_error`	透传自 Gemini 协议的上游
`upstream_error`	上游返回了无法归类的错误
`rerank_error`	重排序接口的错误
`midjourney_error`	Midjourney 相关接口的错误

常见的 `code` 取值

type 为 new_api_error 时，code 指出具体原因。

请求本身的问题

`code`	含义
`invalid_request`	请求不合法
`bad_request_body`	请求体无法解析
`read_request_body_failed`	读取请求体失败
`convert_request_failed`	请求无法转换为上游协议
`model_not_found`	模型不存在或不在可调用范围内
`access_denied`	访问被拒绝，例如 IP 不在允许列表中
`sensitive_words_detected`	命中敏感词拦截
`prompt_blocked`	提示词被上游拒绝

额度与计费

`code`	含义
`insufficient_user_quota`	账户额度不足
`pre_consume_token_quota_failed`	预扣费失败，通常仍是额度不足
`model_price_error`	该模型缺少可用的计价配置
`count_token_failed`	Token 计数失败

渠道与上游

`code`	含义
`channel:no_available_key`	该模型当前没有可用的上游账号
`channel:invalid_key`	上游账号凭据失效
`channel:response_time_exceeded`	上游响应超时
`channel:model_mapped_error`	模型映射配置有误
`get_channel_failed`	未能选出可用渠道
`do_request_failed`	向上游发起请求失败
`bad_response_status_code`	上游返回了非成功状态码
`bad_response` / `bad_response_body`	上游响应无法解析
`empty_response`	上游返回空响应

channel: 前缀的错误来自上游账号而不是你的请求。网关会先自动切换到下一个可用账号，只有全部账号都不可用时才把错误返回给调用方。

验证

打印完整的状态码与响应体：

curl -i https://ai.roibest.com/v1/chat/completions \
  -H "Authorization: Bearer $ROIBEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"does-not-exist","messages":[{"role":"user","content":"hello"}]}'

模型名不存在时返回带 model_not_found 的错误体，可以用它确认客户端的错误处理路径是通的。

常见问题

哪些错误值得重试？ 429 和 5xx。4xx 里的其他状态是请求本身的问题。

message 里的信息被截断了。 脱敏是有意的。到控制台的错误记录里按密钥、模型、状态码和错误类别筛选，能看到更完整的分类。

一直返回 channel:no_available_key。 该模型当前没有可用的上游账号，换一个模型或联系管理员。

错误码