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

# 错误码

> 请求被 TokenHub 拒绝时的状态码、错误码，以及对应的处理办法。

TokenHub 在把请求转给模型之前会做一系列检查。任何一项不通过，就返回对应的 HTTP 状态码和下面这样的响应体：

```json theme={null}
{
  "error": {
    "code": "organization.concurrency_exceeded",
    "message": "organization concurrency exceeded"
  }
}
```

按 `code` 在下面的表里查。如果错误体长得不一样，说明请求已经到了模型那边，是上游返回的错误。

## 鉴权与客户端

| 状态码 | code | 原因 | 怎么办 |
| - | - | - | - |
| 401 | `api_key.invalid` | 密钥缺失、填错，或已被吊销 / 删除 | 检查密钥是否完整，到控制台确认密钥还在 |
| 403 | `api_key.suspended` | 密钥被平台管理员停用 | 联系平台管理员 |
| 403 | `auth.user_disabled` | 创建这把密钥的账号被停用 | 联系平台管理员 |
| 403 | `organization.disabled` | 密钥所属的个人或团队被停用 | 联系平台管理员 |
| 403 | `client.not_allowed` | 这个分组只允许官方客户端（Claude Code、Claude 桌面版、Codex） | 改用官方客户端，或换一个允许所有客户端的分组 |
| 403 | `client.version_too_old` | Claude Code 版本低于平台要求 | 按提示升级 Claude Code 后重启 |
| 403 | `client.version_too_new` | Claude Code 版本高于平台允许的范围 | 按提示降级，并关闭自动更新（环境变量 `DISABLE_AUTOUPDATER=1`） |
| 403 | `client.version_invalid` | 无法识别 Claude Code 版本 | 确认使用的是官方 Claude Code |

## 余额与额度

| 状态码 | code | 原因 | 怎么办 |
| - | - | - | - |
| 402 | `billing.payment_required` | 可用余额不足 | [充值](https://docs.aitokenhub.vip/console/billing.md)，或减少同时进行的请求 |
| 402 | `api_key.budget_exceeded` | 密钥累计用量达到支出上限 | 在密钥编辑里调高上限，或重置累计用量 |
| 402 | `membership.budget_exceeded` | 你在团队里的成员额度用完了 | 联系团队管理员调整额度 |
| 409 | `organization.frozen` | 余额为负，已欠费冻结 | 充值补足欠款，自动解冻 |

qlaude 设备用量达到设备的支出上限时，同样返回 402，在设备设置里调高上限或重置累计用量即可。

## 并发与线路

| 状态码 | code | 原因 | 怎么办 |
| - | - | - | - |
| 429 | `organization.concurrency_exceeded` | 同时进行的请求超过了个人 / 团队的并发上限 | 稍后重试，或减少并行任务。上限是全部密钥和设备共用的 |
| 429 | `account.rpm_exceeded` | 线路当前繁忙 | 稍后重试 |
| 503 | `account.no_available` | 分组里暂时没有可用线路 | 稍后重试；持续出现请联系平台管理员 |
| 503 | `gateway.unavailable` | 网关暂时无法处理请求 | 稍后重试 |
| 503 | `client.policy_unavailable` | 服务刚启动，策略还没加载好 | 稍后重试 |

## 分组

| 状态码 | code | 原因 | 怎么办 |
| - | - | - | - |
| 422 | `route_group.inactive` | 密钥绑定的分组已被停用或删除 | 在密钥编辑里换一个分组 |
| 403 | `route_group.not_visible` | 你的账号当前无权使用这个分组 | 在密钥编辑里换一个分组，或联系平台管理员 |

## 其他状态码

* **404**：请求的路径不存在。检查 base URL 是否多了或少了 `/v1`，见 [接口地址](https://docs.aitokenhub.vip/integrations/api.md)。
* **400 / 5xx 且错误体不是上面的格式**：来自模型上游，例如请求参数不合法、上下文超长。这类失败的请求不收费。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.