错误码

HTTP 状态码

状态码	含义	处理建议
400	请求参数错误或上游不支持该参数	检查 JSON、模型名、tool_choice、response_format 等参数。
401	API Key 缺失或错误	检查 Authorization: Bearer <API Key> 头。
403	当前 Key 无权限访问该模型，或额度受限	联系运营方确认模型权限、余额或额度。
404	路径不存在或模型名不存在	确认是 /v1/chat/completions 而非 /v1/chat/completion；模型名与 /v1/models 返回一致。
429	请求过快或额度限制	降低并发，增加指数退避重试。
500	网关或上游异常	稍后重试；持续出现时联系运营方。
502 / 503 / 504	上游服务异常或超时	指数退避重试，必要时切换模型。

排查 404

404 通常是以下两种之一：

• 路径写错：请求路径不是 /v1/chat/completions。常见错误：少写 s（/v1/chat/completion）、漏掉 /v1/、带了多余的尾部斜杠。
• 模型名错误：路径正确但 model 字段不在 可用模型 清单中。可以通过 GET /v1/models 实时核对。

排障建议先确认请求路径与方法（必须是 POST /v1/chat/completions），再核对模型名是否与服务端拼写完全一致（大小写、连字符）。

重试策略

推荐策略

• 对 429、500、502、503、504 做指数退避重试。
• 起始退避 1 秒，每次翻倍，最多 5 次。
• 对非幂等业务（例如带支付/写库副作用）不要无脑重试。
• 流式请求中途断开，重试时建议从头发送，而不是续传。

日志最佳实践

• 记录：请求时间、模型名、HTTP 状态码、错误消息、业务 request id。
• 不要在日志中写完整 API Key（脱敏到前 4 / 后 4 即可）。
• 不要记录请求体的敏感字段（用户身份、支付信息）。
• 上游错误信息要原样保留：4xx 通常表示客户端可以修请求，5xx 通常表示服务端问题。

报告问题

持续遇到 5xx 或异常 4xx 错误时，请将以下信息发送至 info@aiqizhilian.tech：

• 出现时间（UTC 或东京时间均可）
• 调用模型名
• HTTP 状态码与响应 body（脱敏后）
• 客户端 IP（用于网关日志关联）
• 出现频率（偶发 / 持续 / 100%）

不要在工单中包含完整 API Key。