API 401 报错：INVALID_API_KEY、API_KEY_REQUIRED 怎么解决

调用 HRouter 返回 HTTP 401，说明网关没有认出你的 Key。绝大多数情况是 Key 复制不完整、带了空格，或者这个 Key 已经被停用。按下面的顺序检查，通常几分钟就能解决。

先看返回的错误码

错误码	返回信息	含义
`INVALID_API_KEY`	Invalid API key	Key 不存在或不正确
`API_KEY_REQUIRED`	API key is required in Authorization header...	请求里根本没带 Key
`API_KEY_DISABLED`	API key is disabled	Key 已被停用
`USER_INACTIVE`	User account is not active	Key 所属账号不可用
`USER_NOT_FOUND`	User associated with API key not found	Key 所属账号不存在

客户端有时只显示 “401” 或 “Authentication failed”，把完整的响应内容打印出来，错误码一目了然。

按可能性从高到低排查：

复制不完整或带空格。在 API 密钥页面用复制按钮重新复制完整 Key，粘贴时检查前后没有空格、换行或引号。列表里显示的缩略值不是完整 Key。
配错了位置。Key 填进了 Base URL 字段，或者 Base URL 和 Key 填反了。
用了别的服务的 Key。HRouter 的 Key 以 sk- 开头，但并非所有 sk- 开头的 Key 都是 HRouter 的。
Key 已被删除并重建。旧 Key 在删除后立即失效，工具里还是旧值。
多次填错被临时限制。短时间内反复使用错误的 Key，会触发 429 INVALID_AUTH_RATE_LIMITED，等一会儿再试，见 429 限流与额度。

网关支持三种方式传 Key，至少要有一个：

协议	请求头
OpenAI 兼容	`Authorization: Bearer sk-xxxxx`
Anthropic	`x-api-key: sk-xxxxx`
Gemini	`x-goog-api-key: sk-xxxxx`

常见原因是环境变量没读到：代码里写的是 os.environ["HROUTER_API_KEY"]，但当前终端没有设置。先打印出来确认：

echo $HROUTER_API_KEY

Windows PowerShell 用 echo $env:HROUTER_API_KEY。不要把 Key 放进 URL 查询参数，网关不接受这种用法。

到 API 密钥页面查看这个 Key 的状态。被停用的 Key 需要重新启用，或者新建一个。怀疑泄露而停用的 Key，不要再启用，换新的。

用 curl 单独验证 Key，排除工具配置的干扰：

curl -i https://hrouter.net/v1/models \
  -H "Authorization: Bearer $HROUTER_API_KEY"

排查时不要把完整 Key 贴到聊天、截图或公开 issue 里。需要求助时只展示前后几位。如果已经泄露，先停用旧 Key，再新建。