问题排查 · 错误诊断
错误排查
排查身份验证、限流、上游故障与超时问题。
状态码速查
先看状态码，再定位具体原因，通常能省掉一轮来回排查。
| 状态码 | 含义 | 首要排查方向 |
|---|---|---|
| 401 | 身份验证失败 | Key 完整性、请求头格式 |
| 403 | 权限不足 | 模型/分组权限、Key 状态 |
| 429 | 请求频率受限 | 并发量与退避策略 |
| 5xx | 上游服务故障 | 请求标识、模型与时间点 |
401 身份验证失败
- 确认 API Key 完整且没有多余空格。
- 确认请求头格式与所选 API 协议一致。
- 如果当前 Key 已被删除、禁用或泄露，请创建新 Key。
403 权限不足
- 确认 API Key 有权访问请求的模型与分组。
- 检查账号、Key 或所选渠道是否被禁用。
- 如果 Key 启用了 IP 限制，请检查相关配置。
429 请求频率受限
降低并发，并使用带随机抖动的指数退避进行重试。不要让所有失败请求同时立即重试。
const delay = (attempt: number) =>
Math.min(2 ** attempt * 250, 8_000) * (0.5 + Math.random())5xx 与上游服务故障
上游提供商的临时故障可能表现为 500、502 或 503 响应。联系客服前，请记录请求标识、模型、时间以及已脱敏的错误信息。
提交问题证据时，绝不要包含 API Key、Authorization 请求头、完整私密提示词或支付凭据。
请求超时与流中断
- 对于长时间推理或媒体请求，请适当增加客户端超时时间。
- 确认反向代理不会缓冲或提前终止 SSE 流。
- 仅对幂等操作执行自动重试。