401 Unauthorized 错误排查指南

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

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

常见原因

API Key 未填写或 Header 格式错误

Sub2API 要求在每个 HTTP 请求的 Header 中携带认证信息，格式必须为：

Authorization: Bearer YOUR_API_KEY

常见错误包括：

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

正确示例：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx

API Key 包含多余空格或换行

从控制台复制 API Key 时，很容易多复制一个空格或换行符。这会导致服务器端校验失败。

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

api_key = "sk-xxxxxxxxx".strip()
client = OpenAI(
    api_key=api_key,
    base_url="https://sub2api.ruilinlu.com/v1"
)

API Key 已删除或失效

如果你在控制台手动删除过该 Key，或该 Key 因安全原因被系统回收，继续使用旧 Key 会返回 401。

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

使用了错误的 Key

如果你有多个项目或多个环境（开发/生产），可能会把测试环境的 Key 用于生产环境，或反之。

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

print("当前使用的 API Key:", client.api_key[-6:])

排查步骤

1. 检查 Header 格式

   确认请求中带有 Authorization: Bearer YOUR_API_KEY，注意 Bearer 后有一个空格。

2. 清理 Key 中的空白字符

   对 Key 执行 strip() 或直接重新从控制台复制。

3. 在控制台验证 Key 是否存在

   登录 Sub2API 控制台，查看 API Key 管理页面，确认 Key 状态正常。

4. 重新生成 Key 并测试

   如果以上都确认无误，尝试创建一个新的 API Key，替换后再次发起请求。

有效预防

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

如需了解如何创建新的 API Key，请参考 创建 API Key。