▪ troubleshooting
错误排查
按状态码和错误信息定位问题,先检查密钥、余额与请求参数,再决定是否重试。
错误码速查
| 状态 / 信息 | 原因 | 解决办法 |
|---|---|---|
| 401 | API Key 无效、被停用或未携带 | 检查 Authorization 头是否为 Bearer + 密钥;到API Keys确认状态为启用 |
| insufficient_quota | 余额不足(或 Key 的额度上限用尽) | 到余额充值页充值;或提高该 Key 的额度上限 |
| 429 | 触发限流 | 指数退避重试;批量任务降低并发或错峰 |
| 400 | 请求参数不合法 | 检查 model 名称拼写、messages 结构、max_tokens 等参数 |
| content_filter | 内容触发安全策略 | 调整输入内容;这是上游模型的安全策略,与 11book 无关 |
| 5xx | 上游链路异常 | 对可恢复错误做有限次退避重试;持续失败请联系 [email protected] 并附请求标识 |
排查三步法
- 看错误信息:先查看错误响应里的
error.message或message,结合状态码确认原因。 - 看余额与 Key 状态:到控制台确认余额充足、Key 处于启用状态、 Key 的额度上限没被打满。
- 最小化请求:用 curl 发一个输入简短、输出受限的请求复现问题, 排除业务代码干扰后再逐项加参数。
流式请求的特别说明
流式(stream=true)请求一旦开始输出,HTTP 状态码已是 200—— 后续的错误以 SSE 事件中的 error 对象送达,解析时别忘了处理事件流里的错误分支。
提交工单或求助时,请附上 request_id(响应头或错误详情中)与大致时间, 便于快速定位链路日志。