> ## 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.

# 401 Unauthorized 错误排查指南

> 401 表示 API Key 无效或缺失，本指南帮你通过排查认证 Header、Key 状态和格式快速定位问题。

收到 `401 Unauthorized` 说明 Sub2API 无法验证你的请求身份。这类错误通常与 API Key 的填写方式、格式或状态有关，本文将逐一排查常见原因并提供修复方法。

## 常见原因

<Accordion title="API Key 未填写或 Header 格式错误">
  Sub2API 要求在每个 HTTP 请求的 Header 中携带认证信息，格式必须为：

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

  常见错误包括：

  * 忘记了 `Bearer` 前缀
  * 使用 `authorization`（首字母小写）在某些客户端中可能不会报错，但建议保持首字母大写
  * 使用了 `Api-Key` 等其他 Header 名

  正确示例：

  ```http theme={null}
  Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
  ```
</Accordion>

<Accordion title="API Key 包含多余空格或换行">
  从控制台复制 API Key 时，很容易多复制一个空格或换行符。这会导致服务器端校验失败。

  **修复方法**：在代码中对 Key 做 `trim()` 处理，或在粘贴后手动检查首尾是否有空白字符。

  ```python theme={null}
  api_key = "sk-xxxxxxxxx".strip()
  client = OpenAI(
      api_key=api_key,
      base_url="https://sub2api.ruilinlu.com/v1"
  )
  ```
</Accordion>

<Accordion title="API Key 已删除或失效">
  如果你在控制台手动删除过该 Key，或该 Key 因安全原因被系统回收，继续使用旧 Key 会返回 401。

  **修复方法**：登录 Sub2API 控制台，查看该 Key 是否仍在有效 Key 列表中。如已失效，请重新生成。
</Accordion>

<Accordion title="使用了错误的 Key">
  如果你有多个项目或多个环境（开发/生产），可能会把测试环境的 Key 用于生产环境，或反之。

  **修复方法**：在控制台核对当前使用的 Key 是否属于正确的项目环境。你可以在代码中临时打印 Key 的后几位来确认：

  ```python theme={null}
  print("当前使用的 API Key:", client.api_key[-6:])
  ```
</Accordion>

## 排查步骤

<Steps>
  <Step title="检查 Header 格式">
    确认请求中带有 `Authorization: Bearer YOUR_API_KEY`，注意 `Bearer` 后有一个空格。
  </Step>

  <Step title="清理 Key 中的空白字符">
    对 Key 执行 `strip()` 或直接重新从控制台复制。
  </Step>

  <Step title="在控制台验证 Key 是否存在">
    登录 [Sub2API 控制台](https://sub2api.ruilinlu.com)，查看 API Key 管理页面，确认 Key 状态正常。
  </Step>

  <Step title="重新生成 Key 并测试">
    如果以上都确认无误，尝试创建一个新的 API Key，替换后再次发起请求。
  </Step>
</Steps>

## 有效预防

* 将 API Key 存储在环境变量中，避免硬编码在代码里
* 在代码中对 Key 做 `strip()` 处理，防止复制时带入空格
* 为不同环境使用不同的 Key，并在命名时加上环境标识（如 `sk-prod-xxx`、`sk-dev-xxx`）

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