报错排查 · 401

401 Unauthorized:九成是密钥没有正确送到服务端

401 表示「服务端没认出你的身份」,与余额、模型、网络都无关。按下面顺序排查,通常 1 分钟内能定位。

排查顺序

  1. Header 名对不对:OpenAI 兼容接口用 Authorization: Bearer sk-xxx; Anthropic 原生 /v1/messages 用 x-api-key: sk-xxx 加 anthropic-version。两套混用必 401。
  2. 有没有 Bearer 前缀:漏了 Bearer (含空格)会被当成无效令牌。
  3. 密钥是否完整:从控制台重新复制,注意首尾空格与换行。
  4. 密钥是否被禁用/删除:控制台里看该密钥状态,被禁用的密钥一律 401。
  5. 环境变量是否生效:改完要重开终端或重启客户端。

两种协议的写法

OpenAI 兼容bash
curl https://hardysapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}]}'
Anthropic 原生bash
curl https://hardysapi.com/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'
判断法:两个 curl 里只有一个能通,就说明你的代码用错了协议;两个都通,问题在你的程序没把 Header 带出去。

常见伪装成 401 的情况

  • 客户端把密钥存在本地配置里,但另一个字段覆盖了它(例如同时设置了 OPENAI_API_KEY 与自定义密钥);
  • 经过反向代理时 Header 被丢弃,尤其是 Authorization 被 Nginx 的 underscores_in_headers 之类规则干掉;
  • 浏览器前端直连时触发 CORS 预检失败,控制台看到的是 401 之外的网络错误。

常见问题

401 和 403 有什么区别?

401 是身份没被识别(密钥缺失/错误),403 是身份识别了但没有权限(分组不含该模型、密钥被限制)。

为什么同样的密钥在别的客户端能用?

说明密钥本身有效,问题在该客户端发送 Header 的方式(协议、前缀、Header 名)或本地代理。