API 错误码

先保存 HTTP 状态码、响应正文、请求时间和模型名称。不要只记录客户端翻译后的“连接失败”。

400 请求格式错误

常见原因：

• JSON 无效或字段类型错误。
• 缺少 model、messages、input 或协议要求的字段。
• 向模型发送了不支持的参数。
• Claude、Gemini 和 OpenAI 的正文格式混用。

处理：只保留最小必需字段，使用对应协议的示例重新验证。

401 / 403 鉴权或权限错误

依次检查：

1. 密钥是否复制完整且没有空格或换行。
2. OpenAI 是否使用 Authorization: Bearer ...。
3. Claude 是否使用 x-api-key 和 anthropic-version。
4. Gemini 是否使用 x-goog-api-key。
5. 密钥是否启用、未过期、有额度。
6. IP、模型和分组限制是否允许当前请求。

404 地址、端点或模型错误

• 检查是否产生 /v1/v1。
• 检查是否把完整端点填入 Base URL。
• 检查模型名称是否完整一致。
• 检查客户端使用的协议是否存在对应端点。

429 请求过多

429 可能来自请求速率、并发限制或上游拥塞。

处理建议：

• 使用带随机抖动的指数退避。
• 限制并发，不要所有任务同时重试。
• 遵循响应中的 Retry-After（如果提供）。
• 设置最大重试次数和总时间预算。
• 不重试确定性的参数或权限错误。

简单退避序列可以是约 1 秒、2 秒、4 秒，但应加入随机抖动，避免多个实例同步重试。

500 / 502 / 503 服务异常

先确认最小请求的格式正确，再判断是否为临时渠道异常。对于无副作用的请求，可以短暂退避后重试；持续失败时更换当前分组支持的模型或等待恢复。

不要把所有 5xx 无限重试。代理工作流或图片生成可能产生费用或重复副作用。

超时但没有状态码

这通常发生在客户端、代理或网络层：

• DNS 或 TLS 连接失败。
• 本机代理阻断。
• 客户端总超时过短。
• 流式连接被中间层缓冲或关闭。

先使用 curl 直连并查看详细网络输出，再排查客户端连接问题。

报错信息应如何记录

时间（含时区）：
客户端及版本：
请求协议：
请求地址（不含密钥）：
模型：
HTTP 状态码：
响应错误码与消息：
站内是否有使用日志：