HTTP 状态码表示请求失败的大类原因。你在 API 调用、第三方客户端或“对话”中看到 500、503、429 等状态码时，可以先按状态码判断问题范围，再结合“控制台与用量”中的失败记录排查。
常见状态码
| 状态码 | 常见含义 | 处理方式 |
|---|
400 Bad Request | 请求格式或参数不合法，例如 JSON 错误、字段类型错误、模型参数超出范围、接口路径与请求体不匹配 | 检查请求体、Content-Type、模型名称和参数；先用最小请求重试 |
401 Unauthorized | 未提供 API 密钥，密钥格式错误，或 Authorization: Bearer 写法不正确 | 确认请求头包含 Authorization: Bearer sk-...，并使用未删除、未禁用的密钥 |
403 Forbidden | 当前账户或密钥无权完成请求，常见于余额不足、密钥额度用完、密钥过期、模型或 IP 限制 | 检查账户余额、密钥额度、过期时间、模型权限和 IP 限制 |
404 Not Found | 接口路径错误、Base URL 错误，或模型名称不存在 | 确认 Base URL、端点路径和模型名称；模型名称建议从模型广场复制 |
408 Request Timeout | 请求在规定时间内没有完成 | 缩短输入、减少附件或输出长度后重试；也可以切换响应更快的模型 |
413 Payload Too Large | 请求体、附件或上下文过大 | 压缩文件、拆分内容、缩短上下文，或减少一次请求中的附件数量 |
415 Unsupported Media Type | Content-Type 或上传文件格式不受支持 | 按接口要求设置 Content-Type，并确认文件格式受当前能力支持 |
422 Unprocessable Entity | 请求格式能被解析，但内容不符合当前接口或模型要求 | 检查消息结构、工具调用、图片数量、文件类型和模型能力 |
429 Too Many Requests | 请求过于频繁、并发数过高，或触发速率限制 | 降低并发，增加重试间隔，按指数退避重试 |
500 Internal Server Error | 服务处理请求时出现异常，或模型响应无法正常处理 | 稍后重试；如果持续出现，记录请求时间、模型名称和错误信息后联系支持 |
502 Bad Gateway | 请求链路中的服务返回异常响应 | 重试一次；若多次出现，切换模型并保留失败记录 |
503 Service Unavailable | 当前模型或服务暂时不可用，可能是通道繁忙、无可用线路或服务维护 | 稍后重试，或切换其他可用模型 |
504 Gateway Timeout | 模型响应超时 | 缩短输入、降低最大输出长度、减少附件，或切换模型后重试 |
排查顺序
- 先确认失败发生在“对话”、API 调用，还是第三方客户端。
- 查看 HTTP 状态码和返回的错误信息。
- 打开“控制台与用量”页面，找到同一时间段的失败记录。
- 对照上表检查 Base URL、模型名称、请求体、密钥状态、余额和限制条件。
- 如果同一请求连续失败，先用更短输入或更简单参数重试，再切换模型验证是否为模型可用性问题。
联系支持时不要发送完整 API 密钥、密码或敏感业务数据。API 密钥最多只保留前后几位用于定位。
联系支持时提供什么
- 失败发生时间和大致时区。
- 使用入口：对话、API 调用、Cursor、Claude Code、Codex 或其他客户端。
- HTTP 状态码，例如
500、503、429。
- 模型名称、接口路径和 Base URL。
- 返回的错误信息或截图。
- 控制台与用量中的失败记录信息。
- 如响应中包含请求 ID，也一并提供。
