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

# 错误码

> XRouter 兼容 API 的常见错误响应、状态码和排查方向。

XRouter 的 relay 接口通常返回 OpenAI 兼容错误结构：

```json theme={null}
{
  "error": {
    "message": "token invalid",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_request"
  }
}
```

某些上游错误会保留上游的错误类型或错误码。排查时请同时查看 HTTP 状态码、`error.code`、`error.message` 和控制台用量日志。

## 常见 HTTP 状态码

| 状态码           | 常见原因                     | 排查方向                      |
| ------------- | ------------------------ | ------------------------- |
| `400`         | 请求体格式错误、缺少必填字段、模型参数不兼容   | 对照对应 API 页面检查 JSON、模型名和参数 |
| `401`         | API Key 缺失或无效            | 确认 Key 完整，认证头格式正确         |
| `403`         | 用户、Key、分组、额度或 IP 限制不允许访问 | 检查 Key 状态、模型限制、IP 限制和账户状态 |
| `429`         | 请求触发频率限制或上游限流            | 降低并发，稍后重试，检查工具是否在循环重试     |
| `500`         | XRouter 或上游返回异常          | 查看控制台日志中的请求详情和错误信息        |
| `502` / `503` | 上游不可用、无可用渠道或服务临时异常       | 更换模型或稍后重试                 |

## 常见 `error.code`

| code                             | 含义               | 常见处理                           |
| -------------------------------- | ---------------- | ------------------------------ |
| `invalid_request`                | 请求格式或参数不合法       | 检查 JSON、必填字段、模型名和接口格式          |
| `access_denied`                  | 访问被拒绝            | 检查 Key 的 IP 限制、分组权限或账户状态       |
| `model_not_found`                | 模型不存在或当前 Key 不可用 | 从控制台复制模型 ID，并用 `/v1/models` 验证 |
| `insufficient_user_quota`        | 账户或 Key 可用额度不足   | 到控制台检查账户和 Key 状态               |
| `pre_consume_token_quota_failed` | 请求预扣费失败          | 检查 Key 额度、账户状态和请求预估消耗          |
| `channel:no_available_key`       | 当前模型没有可用上游渠道     | 更换模型或稍后重试                      |
| `channel:model_mapped_error`     | 模型映射失败           | 确认模型 ID 是否来自控制台                |
| `bad_response_status_code`       | 上游返回非成功状态码       | 查看日志中的上游错误信息                   |
| `bad_response_body`              | 上游响应体无法解析        | 记录请求 ID，并查看控制台日志详情             |
| `empty_response`                 | 上游返回空内容          | 重试或更换模型                        |
| `prompt_blocked`                 | 请求内容被上游安全策略拦截    | 修改输入内容或更换符合要求的模型               |

## 请求失败时的最小排查流程

<Steps>
  <Step title="验证 Key">
    使用同一把 Key 请求 `/v1/models`，确认认证和服务地址可用。
  </Step>

  <Step title="确认接口格式">
    OpenAI SDK 使用 `/v1` 和 Bearer token；Claude Code 使用服务根地址；Gemini 客户端使用 `/v1beta`。
  </Step>

  <Step title="复制模型 ID">
    从控制台复制模型 ID，避免手动输入造成大小写或后缀错误。
  </Step>

  <Step title="查看用量日志">
    在控制台按时间、模型或 Key 查找失败请求，确认完整错误信息。
  </Step>
</Steps>