401 鉴权失败：大模型 API Key 排查指南

2026-06-19

HTTP 401 Unauthorized 表示 API key 无效、已过期或无权访问目标模型。401 是纯配置问题，无需重试——直接按排查清单逐项确认，通常 5 分钟内可定位。常见于初次接入、密钥更换或跨平台迁移后。

你大概率是这么撞上的：昨天代码还跑得好好的，今天早上一运行，终端甩出一串 AuthenticationError: Error code: 401，你的第一反应可能是重试三次、重启电脑、甚至怀疑平台挂了。别急着做这些——401 和 429、500 不一样，它不是”暂时性”问题，重试一百次结果都一样，因为服务端在你连模型都没摸到的时候就把请求拦下来了。换句话说，401 出现的那一刻，问题一定在你这边的配置里，不在模型、不在网络、也不在平台负载。把这个心态摆正，排查思路就会从”是不是服务挂了”切换成”是不是我哪个字段填错了”，效率立刻不一样。

实际带新人排查 401，我发现十次里有七八次是下面三个原因之一：key 复制的时候带了空格或换行、.env 改了但进程没重启读到旧值、base_url 填的是别的平台地址。剩下的两三次才是权限或欠费之类”平台侧”的问题。所以清单的顺序也是按”先查最常见的”来排的，不要一上来就怀疑账户被封。

排查清单

检查项	正确做法	常见错误
key 格式	`sk-xxx`（OpenAI）/ 平台指定前缀	多余空格、换行符、截断
key 来源	从平台控制台完整复制	截图 OCR 出现字符识别错误
环境变量注入	`export OPENAI_API_KEY=sk-xxx` 后重启进程	IDE 未重载 .env，进程读到旧值
base_url	与 key 所属平台一致	key 是 A 平台，base_url 指向 B 平台
key 权限	key 有目标模型的访问权限	组织级别限制，key 未授权该模型
key 状态	未过期、未被撤销	测试 key 到期，未在控制台重新生成
账单状态	账户余额充足	余额耗尽，平台返回 401 或 402

这张表看着简单，但每一行背后都有一个具体的坑，值得展开说清楚，不然你对着表格勾完一遍还是不知道问题出在哪。

key 格式那一行，最容易踩的其实不是”少了字符”，而是”多了字符”。最常见的场景是从网页控制台复制 key 时，鼠标多拖了一格，把 key 后面的换行符也带上了；或者从 Excel、飞书文档里复制，末尾粘了一个不可见的空格。这类问题用肉眼看代码几乎发现不了，因为终端打印出来长得一模一样。判断方法很简单：len(api_key) 打印出来的长度，和你在控制台页面上数出来的字符数对不上，多出来的 1-2 个字符基本就是空格或 \n。修法是在读取后统一 api_key.strip()。

环境变量注入那一行是最容易被忽略的连环坑。很多人改完 .env 文件就直接重跑脚本，结果读到的还是旧值——原因是 export 写进了 shell 会话，但你用的是 IDE 内置终端或者一个常驻的 Jupyter kernel，它们各自维护自己的环境变量快照，改宿主 shell 的 .env 根本影响不到已经启动的进程。类似地，用 python-dotenv 的 load_dotenv() 如果在 import OpenAI 之后调用，或者项目里有多个 .env 文件（.env、.env.local、.env.production）加载优先级搞反了，也会读到过期的 key。唯一靠谱的验证方式是打印脱敏后的 key 值，跟控制台里的对一下前 6 位和后 4 位，这也是下面诊断代码里专门加这段逻辑的原因。

base_url 那一行放在这里，是因为它造成的 401 具有极强的迷惑性——你的 key 本身完全没问题，只是被发到了错误的地址。比如你的 key 是从力达云开的通道拿的，但 base_url 还留着之前直连 OpenAI 官方接口的地址，两边的鉴权体系是完全独立的，平台 A 的 key 拿去平台 B 验证，只会得到”key 无效”，报错信息和”key 真的写错了”长得一模一样，单看报错文本根本分不出来，必须回头核对 base_url 和 key 是不是配套的一对。

key 权限那一行容易被有企业账号的团队忽略。很多平台支持给单个 key 设置”可访问模型白名单”，比如某个 key 只开通了 gpt-4o-mini 但没开通 gpt-4o，这种情况下换模型名字重跑，其他配置一个字没动也会从 200 变成 401。排查时留意报错信息里有没有提到具体的 model 或 scope 字段，这通常是权限类 401 独有的线索，跟 key 本身失效的报错文案是不一样的。

快速验证（curl）

用 curl 最小化变量，排除代码问题：

curl https://api.lidayun.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 5
  }'

如果 curl 成功但代码 401，问题在代码侧；如果 curl 也 401，问题在 key 或平台配置。

这一步的价值在于彻底剥离你的应用代码——SDK 版本、框架封装、中间件、重试装饰器，统统不参与，只剩下”这个 key 加这个 base_url 能不能换来一个 200”这一个变量。带徒弟排查问题时我常说一句话：“先证明问题不在你写的代码里，再去查配置”，curl 就是干这个用的最快工具，不需要装任何依赖，任何一台能上网的机器上都能跑。

curl 命令跑完，你应该盯着两个东西：HTTP 状态码和返回体里的 error 字段。如果加上 -i 参数（把它放在 curl 后面），curl 会把响应头一起打印出来，第一行就是 HTTP/1.1 401 Unauthorized 或 HTTP/1.1 200 OK，比翻返回体里一大坨 JSON 找状态码快得多。返回体里正常情况是 {"choices": [...]}，401 的情况下平台通常会返回一个结构类似下面这样的错误对象：

{
  "error": {
    "message": "Incorrect API key provided: sk-abc***xyz.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

留意 code 字段，invalid_api_key 和 insufficient_quota（余额不足触发的类 401/402 错误）虽然都可能表现为鉴权类失败，但根因完全不同，前者要换 key 或修格式，后者要去控制台充值，别把两种情况混着排查，浪费时间。

Python 诊断代码

import os
from openai import OpenAI, AuthenticationError

api_key  = os.environ.get("OPENAI_API_KEY", "")
base_url = os.environ.get("OPENAI_BASE_URL", "https://api.lidayun.com/v1")

# 打印脱敏 key 确认注入
masked = f"{api_key[:6]}…{api_key[-4:]}" if len(api_key) > 10 else "(空或太短)"
print(f"KEY: {masked}  BASE_URL: {base_url}")

client = OpenAI(api_key=api_key, base_url=base_url)

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "ping"}],
        max_tokens=5,
    )
    print("OK:", resp.choices[0].message.content)
except AuthenticationError as e:
    print("401 鉴权失败:", e)
    # e.response.json() 可查看平台返回的详细 error message

这段代码里最关键的不是 try/except，而是打印脱敏 key 那一行——这是我见过最多人跳过、但最能省时间的一步。你脑子里以为环境变量已经生效了，不代表它真的生效了；把 masked 打印出来跟控制台页面上的 key 前后几位肉眼核对一遍，一秒钟就能确认”注入”这一环到底通没通，比盲猜”是不是权限问题”靠谱得多。这里用切片取前 6 位后 4 位而不是全量打印，是为了避免把完整 key 输出到日志文件或 CI 的构建记录里——很多团队的日志系统会被同事、监控平台甚至第三方 SaaS 抓取留存，完整 key 一旦进了日志就等于泄漏，之后只能撤销重新生成。

再说 except AuthenticationError 这里为什么要单独捕获这个异常类型，而不是一个大大的 except Exception。OpenAI SDK（以及大部分兼容 OpenAI 协议的平台 SDK）会把不同的 HTTP 状态码映射成不同的异常子类：401 对应 AuthenticationError，429 对应 RateLimitError，超时对应 APITimeoutError。分开捕获的好处是你可以针对不同错误写不同的处理逻辑——401 应该立即终止并报警（因为重试没有意义），429 应该退避重试，超时可以换更短的 prompt 或降级模型。如果笼统地用一个 except Exception 兜底，你的重试逻辑很可能会对着一个死活不会好转的 401 傻乎乎地重试 5 次，白白浪费时间还可能触发平台的异常请求告警。

Node.js 诊断代码

import OpenAI from "openai";

const apiKey  = process.env.OPENAI_API_KEY ?? "";
const baseURL = process.env.OPENAI_BASE_URL ?? "https://api.lidayun.com/v1";
const masked  = apiKey.length > 10 ? `${apiKey.slice(0, 6)}…${apiKey.slice(-4)}` : "(空)";
console.log(`KEY: ${masked}  BASE_URL: ${baseURL}`);

const client = new OpenAI({ apiKey, baseURL });

try {
  const resp = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "ping" }],
    max_tokens: 5,
  });
  console.log("OK:", resp.choices[0].message.content);
} catch (err) {
  if (err.status === 401) console.error("401 鉴权失败:", err.message);
  else throw err;
}

Node 版本的逻辑和 Python 版一模一样，但注意 err.status === 401 这个判断——不同 SDK 暴露错误码的字段名不统一，有的是 err.status，有的是 err.response.status，还有的把状态码塞在 err.code 里当字符串用（比如 "401" 而不是数字 401）。如果你用的是别的框架封装（比如某些 LangChain.js 的适配层），出错时先 console.log(JSON.stringify(err, null, 2)) 把整个错误对象摊开看一遍，确认字段名再写判断逻辑，不要凭经验硬猜，不同版本之间这个字段名还真的会变。

.env 文件注入

项目推荐使用 .env 文件管理密钥，注意 .env 应加入 .gitignore：

# .env
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.lidayun.com/v1

# Python：pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()   # 在 import OpenAI 之前调用

// Node.js 18.3+
// node --env-file=.env your-script.js
// 或 npm i dotenv 后：
import "dotenv/config";

这里补一个容易被忽略的细节：node --env-file=.env 是 Node 18.3+ 才支持的原生用法，如果你的项目还锁在 Node 16 或 18.0，这个参数会直接报”未知选项”而不是任何和鉴权相关的错误，容易让人误判成 key 的问题。用 node -v 先确认版本，低版本老老实实装 dotenv 包用 import "dotenv/config" 这条路更稳。另外 .env 里千万别在 key 两侧加引号（很多人习惯写成 OPENAI_API_KEY="sk-xxx"），dotenv 大部分版本会把引号也读进去当成 key 的一部分，导致你查了半天格式却发现问题出在这对多余的引号上。

报错文案对照：先看清楚报的是哪种错

不同平台、不同 SDK 版本对同一类问题的报错措辞不完全一样，下面这张表是我实际踩过、也帮人排查过的高频文案，对号入座能省掉很多来回猜测的时间：

报错关键词	根因	修法
`Incorrect API key provided`	key 本身格式错或被撤销	控制台重新复制/重新生成 key
`You didn't provide an API key`	代码里 `api_key` 读到了空字符串	检查环境变量是否真的注入，用脱敏打印验证
`Invalid Authentication` / `no auth credentials found`	请求头没带 `Authorization: Bearer` 或格式错误（漏了 `Bearer` 前缀）	检查 SDK 版本，或手写请求头时核对拼写
`You exceeded your current quota`	余额耗尽，不是 key 格式问题	去控制台充值，跟”401 格式错误”是两码事
`Incorrect API key provided: sk-abc***xyz` 但你确定 key 没错	key 是对的，但 base_url 指向了另一个平台，两边鉴权体系不通	核对 base_url 与 key 是否配套
403 Forbidden（不是 401）	key 有效但没有权限访问这个具体资源/模型/组织	去控制台检查该 key 的模型白名单和所属组织

最后一行专门拎出来说：401 和 403 是两个不同层级的问题，很多人下意识把它们当同一件事处理。401 的意思是”你没证明自己是谁”（鉴权失败，key 本身有问题）；403 的意思是”我知道你是谁，但你没有权限做这件事”（鉴权通过了，但授权不够，比如 key 有效但没开通某个模型，或者账号被限制访问某个地域的资源）。如果你看到的是 403 而不是 401，排查方向应该直接跳到”key 权限”那一项，而不是回头怀疑 key 格式或环境变量注入，那些环节根本不背这个锅。

常见问题

key 正确但仍然 401，如何排除 base_url 问题？ 对比平台文档确认 base_url 末尾是否需要 /v1，例如 https://api.lidayun.com/v1（有 /v1）vs https://api.example.com（无 /v1）。SDK 会自动拼接 /chat/completions，路径错误会导致 404 或 401。

组织账号多 key 如何管理权限？ 平台通常支持对 key 设置模型白名单和预算上限，在控制台”API 密钥”页配置，避免单个 key 权限过大。

CI/CD 流水线里密钥怎么注入？ 使用 GitHub Actions Secrets / GitLab CI Variables，通过环境变量传入，绝不硬编码到代码或 Dockerfile。这里再补一个实战教训：GitHub Actions 的 Secrets 在日志里默认会被自动打码成 ***，但前提是这个值必须完整匹配——如果你在代码里对 key 做了 .strip() 或大小写转换再打印，打码可能会失效，日志里就会漏出真实 key 的一部分。稳妥的做法是永远不要在 CI 日志里打印 key 的任何形式，哪怕是脱敏版本，脱敏逻辑写错一次就前功尽弃。

本地能跑通，部署到服务器/容器后 401，为什么？ 这是我见过最容易让人抓狂的一类 401，因为”代码明明没有改”。常见原因有三个：一是本地 .env 文件没有被打进镜像或没有挂载到容器里，容器里的进程压根读不到那个文件；二是用了 Docker 的场景下，docker run 忘记加 --env-file .env 或 -e OPENAI_API_KEY=xxx，导致容器内环境变量是空的；三是服务器上的系统级环境变量和项目 .env 起了冲突——比如运维之前配置过一个全局的 OPENAI_API_KEY 用于别的项目，系统级变量的优先级在某些启动方式下会盖过项目 .env，导致你以为读的是新 key，实际读到的是别的项目遗留的旧 key。排查时在容器/服务器里直接跑一遍前面的 Python 或 Node 诊断脚本，看打印出来的脱敏 key 是不是你期望的那一个，比凭感觉猜靠谱得多。

多个项目共用一个 key，会不会互相影响导致间歇性 401？ 会，但表现形式通常不是纯粹的 401，而是”有时候好使有时候不好使”。如果平台给单个 key 设置了并发数或调用频率上限，多个项目同时用同一个 key 打接口，超限时有些平台会返回 429（限流）而不是 401，但也有平台在 key 被标记为”异常调用模式”（比如短时间内来自多个不同 IP 的调用）时直接返回 401 作为风控措施。稳妥的做法是给每个项目/每个环境（开发、测试、生产）单独开一个 key，出问题时能立刻定位到是哪个项目在捣乱，而不是所有项目一起背锅、一起排查。这也是本文清单里”key 权限”要单独设置模型白名单和预算上限的原因之一——权限拆得越细，出问题时排查范围越小。

更多接入基础见大模型 API 接入完全指南与接入教程专题。接口正常后若遇速率限制，见 429 限流：指数退避与重试；超时问题见超时与连接管理。