错误状态码

了解 API 和对话中常见 HTTP 状态码的含义，并按状态码定位问题。

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	模型响应超时	缩短输入、降低最大输出长度、减少附件，或切换模型后重试

​

排查顺序

1. 先确认失败发生在“对话”、API 调用，还是第三方客户端。
2. 查看 HTTP 状态码和返回的错误信息。
3. 打开“控制台与用量”页面，找到同一时间段的失败记录。
4. 对照上表检查 Base URL、模型名称、请求体、密钥状态、余额和限制条件。
5. 如果同一请求连续失败，先用更短输入或更简单参数重试，再切换模型验证是否为模型可用性问题。

联系支持时不要发送完整 API 密钥、密码或敏感业务数据。API 密钥最多只保留前后几位用于定位。

​

联系支持时提供什么

• 失败发生时间和大致时区。
• 使用入口：对话、API 调用、Cursor、Claude Code、Codex 或其他客户端。
• HTTP 状态码，例如 500、503、429。
• 模型名称、接口路径和 Base URL。
• 返回的错误信息或截图。
• 控制台与用量中的失败记录信息。
• 如响应中包含请求 ID，也一并提供。