> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误状态码

> 了解 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. 如果同一请求连续失败，先用更短输入或更简单参数重试，再切换模型验证是否为模型可用性问题。

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

## 联系支持时提供什么

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