DEVELOPER · ERRORS
错误码参考
错误返回结构与 OpenAI 一致：{"error": {"message": "...", "type": "...", "code": "..."}}。下面列出最常见的几种。
HTTP 状态码
| 状态码 | 含义 | 处理建议 |
|---|---|---|
200 | 成功 | 正常解析响应 |
400 | 请求参数错误 | 检查 model 名称、messages 格式 |
401 | 认证失败 | 检查 Authorization 头与 Key 是否正确 |
403 | 无权限 | 令牌被禁用，或无权访问该模型分组 |
429 | 限流 / 额度不足 | 降速重试，或检查剩余额度 |
500 | 服务端错误 | 稍后重试；持续出现联系管理员 |
502/504 | 上游网关超时 | 上游模型响应慢，建议启用流式 |
常见错误信息
| message 片段 | 原因 | 解决 |
|---|---|---|
| invalid_api_key | Key 格式错误或已失效 | 到控制台重新复制完整 Key |
| insufficient_quota | 令牌额度耗尽 | 调高额度上限或充值 |
| model not found | model 值拼错或未接入 | 对照模型列表核对 ID |
| rate_limit_exceeded | 触发上游限流 | 降低并发，加退避重试 |
| context length exceeded | 输入超长 | 精简 messages 或换长上下文模型 |
重试建议
- 对
429、500、502/504使用指数退避：1s → 2s → 4s，最多 3 次。 - 流式请求遇到中途断流，建议保留已有内容，用相同 messages 重新发起而非从头重试。
401/403不要重试，先排查 Key 与权限。
遇到无法解决的错误，可在控制台「日志」页查看请求详情，便于定位。