API 错误码与排障手册
最后更新:
接口报错时,先看状态码,再按"鉴权 → 地址 → 模型标识 → 参数 → 限额 → 上游"的顺序排查。多数问题在第三步之前就能定位。
先判断故障属于哪一层
| 现象 | 大概率层级 | 先做什么 |
|---|---|---|
| 所有请求都失败 | 鉴权或地址配置 | 核对 Bearer 头与完整请求地址,不要先怀疑模型 |
| 只有某个模型失败 | 模型标识或权限 | 与控制台中的模型标识逐字比对 |
| 只有特定输入失败 | 参数或上下文长度 | 缩短输入、移除非必需参数后复测 |
| 并发升高后开始失败 | 限额或上游容量 | 降低并发、加入退避重试 |
| 偶发超时或中断 | 网络、超时设置或流式解析 | 记录请求时间与状态码,保留已接收内容 |
状态码含义与处理
| 状态码 | 常见原因 | 处理方式 |
|---|---|---|
| 400 | JSON 语法错误、字段类型不符、必填字段缺失 | 先做语法校验,再移除可选参数定位冲突字段 |
| 401 | 缺少或格式错误的 Authorization 头、凭证已撤销 | 确认 Authorization: Bearer <KEY> 与 Key 状态;不要靠重试解决 |
| 403 | 凭证有效但无该模型或该操作的权限 | 在控制台核对权限与分组配置 |
| 404 | 路径拼接错误、模型标识不存在 | 区分基础地址与完整端点,避免重复拼 /v1 |
| 422 | 参数通过校验但语义不被接受 | 检查取值范围、上下文长度与消息结构 |
| 429 | 频率限制或额度不足 | 看响应正文区分两类;依 Retry-After 做有限退避 |
| 5xx | 上游异常或网关故障 | 记录时间与请求标识,缩短输入后复测,避免无界重试 |
| 读取超时 | 客户端超时过短、长文本生成、上游排队 | 区分连接超时与总超时;超时不代表上游未执行 |
| 流式中断 | 代理缓冲、SSE 解析错误、连接被重置 | 检查代理是否缓冲响应、按事件边界解析,保留部分内容并标记未完成 |
最容易被忽略的三个配置错误
- 基础地址与完整端点混用。自动拼接路径的 SDK 应只填基础地址;手写请求才使用完整端点。两者混用会出现路径重复的 404。
- 把展示名当作模型标识。页面上的模型名称便于阅读,接口需要的是控制台给出的标识。
- 把密钥放进前端或日志。前端环境变量会进入浏览器代码;日志与崩溃报告同样需要脱敏。
重试与幂等
- 只对可能恢复的错误重试(如 429、部分 5xx),使用指数退避并限制次数;
- 不要在鉴权失败、参数错误上重试,这只会放大失败并可能触发风控;
- 可能触发外部副作用的任务,请在应用侧用任务标识做去重,不要假定接口提供幂等保证;
- 超时后重试可能产生重复消耗,建议在重试前先确认上一次的结果。
反馈问题时请提供
- 发生时间(含时区)、模型标识与使用的完整请求地址;
- HTTP 状态码与响应中的错误信息、请求标识(如有);
- 脱敏后的请求片段与是否使用流式;
- 是否可复现、复现频率与当时的并发量。
请务必移除真实 API Key、个人数据与敏感正文后再发送。
上线前的自检清单
- 正常请求、无效 Key、无效模型、超时与取消各测一遍;
- 确认错误提示对终端用户可理解,不泄露内部地址与凭证;
- 确认超时、重试与并发上限已设置,而不是依赖默认值;
- 确认日志中不含密钥与敏感正文,并保留可用于对账的用量字段。