按状态码定位
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 400 | 请求体或协议不匹配 | 检查 JSON、路由、模型 ID 与协议头（Claude 请求保留 anthropic-version） |
| 401 | 密钥无效或缺失 | 重新复制密钥，检查 Bearer / x-api-key；若可能泄露立即轮换 |
| 403 | 余额不足或无权限 | 检查钱包余额、密钥额度、模型权限与分组访问 |
| 429 | 触发限流 | 使用带抖动的指数退避，降低并发，确认限流来自网关还是上游 |
| 5xx | 上游或路由故障 | 保留 request id，联系管理员检查渠道健康与上游状态 |
| 超时 | 首字很慢或流中断 | 减小 prompt、确认 stream=true、检查代理是否缓冲 SSE |
推荐排查顺序
- 先做最小请求：
curl /v1/models验证认证是否正常。 - 再发一个最小 chat 请求，区分认证错误与模型 / 协议错误。
- 阅读响应体中的错误信息与 request id。
- 在「用量日志」中核对是否有该请求的记录。
密钥泄露处理
- 立即在控制台停用或删除该密钥。
- 创建新密钥并更新所有使用方（环境变量、密码管理器、客户端配置）。
- 检查用量日志中有无陌生请求，确认泄露影响范围。
报障需要提供什么
请求时间、路由、模型 ID、HTTP 状态码、request id、客户端版本与脱敏后的错误信息。不要发送密钥本身。