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

# API Key 无法使用的排查方法

> API Key 无法使用时，排查格式错误、账户余额不足、Key 已删除等常见原因。

当你确认 API Key 已经填入代码，但请求仍然失败时，问题可能出在 Key 的格式、账户状态或权限上。本文提供一个系统的排查清单，帮助你逐一验证。

## 排查清单

<Steps>
  <Step title="检查 Key 是否复制正确">
    从控制台复制 API Key 时，容易多复制空格或换行符。建议粘贴后检查首尾是否有空白字符，或在代码中对 Key 执行 `strip()` 处理。

    ```python theme={null}
    api_key = os.environ.get("SUB2API_KEY", "").strip()
    ```
  </Step>

  <Step title="检查 Header 格式">
    确认请求头格式严格为：

    ```http theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    常见错误包括：缺少 `Bearer` 前缀、使用 `Api-Key` 作为 Header 名、或 `Bearer` 与 Key 之间没有空格。
  </Step>

  <Step title="在控制台验证 Key 是否存在">
    登录 [Sub2API 控制台](https://sub2api.ruilinlu.com)，进入 API Key 管理页面，确认当前使用的 Key 仍在列表中且状态正常。如果 Key 已被删除，需要重新创建。
  </Step>

  <Step title="检查账户余额">
    Sub2API 采用 Token 计费模式（按量付费）。如果账户余额不足，即使 Key 格式正确，请求也可能被拒绝。请在控制台查看余额，如有需要请充值。具体操作请参考 [余额充值](/billing/balance-topup)。
  </Step>

  <Step title="创建新的 API Key 并测试">
    如果以上步骤均确认无误但请求仍失败，尝试在控制台生成一个新的 API Key，替换后再次测试。新 Key 可以排除旧 Key 因未知原因被标记为无效的情况。
  </Step>
</Steps>

## 常见错误对照表

| 现象               | 可能原因                 | 解决方法                                               |
| ---------------- | -------------------- | -------------------------------------------------- |
| 401 Unauthorized | Header 格式错误或 Key 已失效 | 按照步骤 1 和 2 检查格式；按照步骤 3 确认 Key 状态                   |
| 403 Forbidden    | 地区限制或余额不足            | 检查是否从支持地区访问；参考 [余额充值](/billing/balance-topup) 确认余额 |
| 自定义 Key 错误       | Key 已被手动删除           | 创建新 Key                                            |

## 有效预防

* 将 API Key 存储在环境变量中，避免硬编码
* 复制 Key 后习惯性地执行 `strip()` 清理空白字符
* 定期检查控制台中的 Key 列表和账户余额，避免因余额耗尽导致服务中断

如需创建新的 API Key，请参考 [创建 API Key](/getting-started/create-api-key)。