错误码排查

先看 HTTP 状态码，再检查 Key、余额、Base URL、模型 ID。大多数接入问题都能在这四项里定位。

快速定位

状态码	含义	最可能原因
400	请求格式错误	JSON、参数或模型能力不匹配
401	认证失败	Key 错误或请求头缺失
402	余额不足	账户额度不够
403	无权限	模型未开放或账户受限
404	找不到资源	URL、路径或模型 ID 错误
429	请求过快	并发或频率超过限制
500	服务端错误	中转服务或上游临时异常
502	上游错误	模型供应商异常或连接失败

400 - 请求格式错误

常见原因：

• JSON 格式不合法。
• messages 格式不符合接口要求。
• 给图片模型传了文本模型参数，或给文本模型传了图片参数。
• 模型不支持当前字段，例如某些模型不支持 tools。

处理方式：先用 快速开始 的最小示例跑通，再逐步加参数。

401 - 认证失败

检查顺序：

1. 请求头是否是 Authorization: Bearer sk-YOUR_TOKEN。
2. Bearer 后面是否有一个空格。
3. Key 是否完整复制，没有多余空格。
4. 控制台中该 Key 是否已删除或过期。

402 - 余额不足

登录 控制台 查看余额。余额不足时，前往 获取兑换码 充值。

403 - 无权限

可能原因：

• 当前账号没有该模型权限。
• 模型临时下线或只对白名单开放。
• 请求触发风控策略。

如果确认余额和 Key 都正常，请加入用户群并提供模型 ID。

404 - 路径或模型不存在

优先检查：

场景	正确写法
OpenAI SDK	base_url="https://zrapi.org/v1"
Claude SDK	base_url="https://zrapi.org"
ChatBox Host 字段	按字段名决定是否带 /v1
对话端点	/v1/chat/completions

模型 ID 必须和 模型与价格 页面一致。

429 - 请求频率过高

处理方式：

1. 降低并发。
2. 加指数退避重试。
3. 避免同一秒大量短请求。
4. 需要更高限额时加入用户群说明使用场景。

500 - 服务端错误

通常是临时问题。可以稍后重试，或先切换到其他模型确认是否为单模型异常。

502 - 上游错误

通常表示上游模型供应商连接失败、超时或返回异常。建议：

1. 等待 1 到 3 分钟后重试。
2. 切换同类模型。
3. 如果持续出现，加入用户群并提供时间、模型、请求 ID 或完整报错。

查看 FAQ加入用户群检查模型 ID