错误码与排障
从最小请求开始，按地址、权限、模型和服务状态逐项排查。
常见 HTTP 状态
以下是排查方向；具体原因以响应中的错误信息为准。
| 状态码 | 优先检查 |
|---|---|
| 400 | JSON 格式、模型参数、上下文长度，或模型不支持的能力 |
| 401 | 密钥是否完整、正确、启用且未过期；认证头是否正确 |
| 403 | 分组、模型权限、IP 限制及账号状态 |
| 404 | 请求路径和模型 ID；是否多写或漏写了 /v1 |
| 429 | 请求频率、并发限制、额度及上游容量 |
| 500 / 502 / 503 | 平台或上游暂时异常，保留请求标识再排查 |
| 504 | 网关或上游超时，缩短输入并检查客户端超时设置 |
地址与协议不匹配
收到 HTML 而非 JSON，通常需要检查是否把控制台页面地址当作 API 地址。OpenAI 兼容请求与 Anthropic Messages 请求的路径及认证方式不同。
SDK 的 Base URL 不应直接填 /chat/completions 或 /messages 完整路径，除非该工具明确要求完整端点。
找不到模型
重新查询 GET /v1/models，核对完整模型 ID，并检查密钥分组和模型限制。不要删除 provider/ 前缀，也不要根据模型显示名称猜 ID。
重试与超时
仅对暂时性错误采用有限次数的退避重试；优先遵循响应中的 Retry-After。认证失败、参数错误应先修正配置。超时不一定代表服务端未执行，重试可能产生额外调用和费用。
提交排障信息
提供工具名称及版本、发生时间和时区、HTTP 状态码、模型 ID、脱敏后的错误信息及请求标识（如果有）。不要附上 API 密钥、Cookie 或包含敏感内容的完整请求。
更多记录查看 日志功能。