错误码说明
401 / 403 / 404 / 429 / 5xx 的含义、五步排查法与减少报错的实践。
接口出错时，先看 HTTP 状态码和响应体里的错误信息，再按本文的对照表定位。大多数问题都能在前 3 条里解决。
状态码对照
| 状态码 | 含义 | 常见原因与处理 |
|---|---|---|
| 400 Bad Request | 请求参数不合法 | JSON 格式错误、缺少必填字段（如 model、messages）；对照接口文档检查请求体 |
| 401 Unauthorized | 鉴权失败 | 密钥错误 / 已删除 / 已过期；见鉴权方式排查清单 |
| 403 Forbidden | 无权访问 | 该密钥或账户没有所请求模型的权限；确认模型在模型广场对你是可用状态 |
| 404 Not Found | 资源不存在 | 通常是模型 ID 拼写错误；到模型广场复制准确的模型 ID |
| 429 Too Many Requests | 触发限流 | 请求过于频繁。退避重试（指数间隔），或降低并发；持续出现联系平台调整配额 |
| 5xx | 服务端异常 | 平台或上游模型临时故障。先用相同参数重试一次；若持续失败，携带日志页的请求记录联系支持 |
排查步骤
- 确认密钥有效：在控制台「API 密钥」页确认该密钥存在且未过期，必要时删除重建。
- 确认模型 ID 正确：从模型广场复制，不要手写。
- 看响应体错误信息：错误响应通常带
error.message，会说明具体原因（如余额不足、参数缺失）。 - 查日志：控制台日志页能逐笔看到请求的状态码、延迟与消耗——确认问题是否只发生在特定模型或密钥上。
- 仍然无法解决：带上日志页的时间点与状态码联系支持。
减少报错的实践
- 用官方 SDK 发请求（自动处理重试、超时与协议细节）；
- 对 429 / 5xx 实现指数退避重试，不要立即疯狂重试；
- 生产密钥设置消费上限，避免异常流量打爆余额。