认证与 401

关于 401 Unauthorized、Invalid API key、令牌已过期、余额不足 的完整排查。

你会看到什么

现象	属于
`401 Unauthorized`	鉴权没通过
`Invalid API key`	令牌无效
`API key is required`	请求头里没带令牌
`令牌已过期` / token expired	令牌有效期到了
`余额不足` / `Insufficient balance`	账户额度用尽
`403 Forbidden`	有身份但没权限（白名单/模型限制）

先做这一件事：看 `code` 字段

这是最高效的一步，能立刻把问题分成两半。

平台返回的 401 有两种，code 字段完全不同：

`code`	含义	你该往哪查
`API_KEY_REQUIRED`	请求头里根本没有令牌	「配置没生效」类
`INVALID_API_KEY`	带了令牌，但令牌无效	「令牌本身有问题」类

实测原文：

缺少鉴权头：

json

{
  "code": "API_KEY_REQUIRED",
  "message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}

令牌无效：

json

{ "code": "INVALID_API_KEY", "message": "Invalid API key" }

这段 message 本身就把答案写出来了

API_KEY_REQUIRED 的文案里列明了平台接受的三种鉴权头： Authorization: Bearer、x-api-key、x-goog-api-key。对着这三者检查你的请求头就行，不用猜。

如果你用的是 Gemini 原生路径

/v1beta/... 返回的是 Gemini 风格的结构，格式和上面不一样：

json

{
  "error": {
    "code": 401,
    "message": "API key is required",
    "status": "UNAUTHENTICATED"
  }
}

令牌无效时 message 变 Invalid API key，status 仍是 UNAUTHENTICATED。

现象一：`API_KEY_REQUIRED`（没带令牌）

原因

请求头里没有可用凭据。注意：这通常不是令牌本身错了，而是配置没生效。

最常见的是这三种：

环境变量没被读到 —— 你 export 了，但程序是从另一个终端/IDE 启动的，继承不到
客户端没重启 —— 改完配置，进程还在用旧的
请求头格式不对 —— 少了 Bearer 前缀，或字段名拼错

解决

按顺序排查：

确认请求头格式正确

正确的请求头（三选一）

Authorization: Bearer sk-你的令牌x-api-key: sk-你的令牌x-goog-api-key: sk-你的令牌

确认环境变量在当前进程里可见
检查环境变量
```
echo $ANTHROPIC_BASE_URLecho $ANTHROPIC_AUTH_TOKEN
```
输出为空 = 没设置成功。常见原因是写进了 ~/.bashrc 但当前 shell 没重新加载 —— 执行 source ~/.bashrc，或直接关掉终端重开。
确认程序是从这个终端启动的
从 IDE、Docker、systemd 服务启动的程序不会继承你在终端里 export 的变量。要么在程序自己的配置里写，要么在启动脚本里显式传入。
重启客户端
重启后复验
```
curl https://cn.fluxtoken.ai/v1/models \  -H "Authorization: Bearer sk-你的令牌"
```
这条命令能列出模型，就说明令牌和网络都通了。

现象二：`INVALID_API_KEY`（令牌无效）

原因

令牌确实带上了，但平台不认。翻来覆去就是这几种：

原因	怎么确认
令牌写错	复制时漏字符、多了空格或换行
令牌被删除	控制台令牌管理里已经找不到它
令牌已过期	建令牌时设了过期时间，现在过了
令牌额度上限到了	建令牌时设的「额度上限」被用完（注意：这是单个令牌的上限，不是账户余额）
用了别家站的 Key	拿 Claude 官方、OpenAI 官方或别的中转站的 Key 来用
协议填法错配	把 Anthropic 的填法用在 OpenAI 兼容端点上（或反过来）
IP 白名单不匹配	令牌设了 IP 白名单，你当前出口 IP 不在里面

解决

重新复制一次令牌
控制台 → 令牌管理 → 找到该令牌 → 用复制按钮复制，不要手打。粘贴后检查首尾有没有多余空格或换行：
检查令牌首尾有无空白
```
echo -n "sk-你粘贴的令牌" | cat -A
```
确认令牌在控制台里还在、还没过期
令牌管理里能看到创建时间、过期时间、已用额度。过期了就新建一个。
确认这是本平台的令牌
FluxToken 的令牌在控制台的令牌管理里生成。 模型提供商的官方 Key 在这里一律无效 —— 反过来也一样。
确认端点与协议的搭配正确
这一条最容易错，对照着看：
你在接什么基础地址谁补 /v1
OpenAI SDK / Codex https://cn.fluxtoken.ai/v1 你补
Anthropic SDK / Claude Code https://cn.fluxtoken.ai SDK 补
详见接口总览。
检查令牌的 IP 白名单与模型限制
如果建令牌时填过 IP 白名单或模型限制，它们会分别导致 403 或 模型不存在。不确定就先建一个不设限制的新令牌验证通路。

你在接什么	基础地址	谁补 `/v1`
OpenAI SDK / Codex	`https://cn.fluxtoken.ai/v1`	你补
Anthropic SDK / Claude Code	`https://cn.fluxtoken.ai`	SDK 补

现象三：`余额不足`

原因

账户的可用额度用尽了。

注意区分两个不同的「额度」：

概念	位置	说明
账户余额	控制台钱包	整个账号的总额度。为 0 时所有请求都失败
令牌额度上限	令牌管理	单个令牌的消费上限。到顶时只有这个令牌失败

解决

看账户余额 —— 控制台 → 钱包。余额低于阈值时平台会发邮件/站内提醒，提醒里的充值链接指向控制台的充值页。
需要充值 → 充值入口：https://fluxtoken.ai/purchase（支付宝 / 微信）。 实时应付金额与到账额度以充值页实际显示为准，文档不写死汇率。
如果是令牌上限到了 —— 去令牌管理调高或去掉该令牌的额度上限，不用充值。

余额为 0 时也可能表现为 401

有些客户端会把「余额不足」也归到认证失败里显示。如果你确认令牌没写错却一直认证失败，顺手看一眼余额。

现象四：`403 Forbidden`

原因

身份是有效的，但这个令牌没被授权做这件事。 常见两种：

IP 白名单不匹配 —— 令牌设了 IP 白名单，你当前出口 IP 不在名单里（换了网络、开了代理、用了移动网络都会变）
模型限制 —— 令牌设了「允许的模型」清单，你调的模型不在其中

另外，账号或所在地区受限也会返回 403，见支持的国家和地区。

解决

令牌管理 → 编辑令牌 → 检查 IP 白名单。不确定就先清空它，验证通路后再加回来。
检查 模型限制。同样是先清空验证。
换一个没有任何限制的新令牌测试。能通就说明是原令牌的限制配置问题。

一次性排查脚本

不确定问题在哪时，跑这一条命令。它绕开所有客户端，直接验证「令牌 + 网络」这两件事：

最小验证

curl -s -o /dev/null -w "%{http_code}\n" https://cn.fluxtoken.ai/v1/models \  -H "Authorization: Bearer sk-你的令牌"

对照返回值：

返回	说明	下一步
`200`	令牌和端点都正常	问题在客户端配置，不是令牌
`401` + `INVALID_API_KEY`	令牌本身有问题	见「现象二」
`401` + `API_KEY_REQUIRED`	令牌没被发出去	见「现象一」
`403`	白名单或模型限制	见「现象四」
连不上 / 超时	网络问题	连接与超时

这个 200 很有价值

/v1/models 需要鉴权，所以它返回 200 就同时证明了「令牌有效」和「网络通」。客户端里出问题时，先跑这一条来分割问题范围。

还不行怎么办

服务状态页 https://status.fluxtoken.ai/ —— 确认不是上游波动
控制台的错误请求记录 —— 里面有失败原因和时间，比猜快得多
确认地区规则 —— 平台不向中国大陆的个人或组织提供服务，见支持的国家和地区
进群 —— QQ 群 1108757955 · Telegram https://t.me/fluxtokengroup

进群请附上：报错的 code 字段、你用的客户端、端点地址、完整报错原文。

令牌不要贴到群里

排查时需要的话，只贴前几位和后几位（例如 sk-abc...xyz），中间打码。完整令牌等同于账号权限，被拿到就能消耗你的额度。

认证与 401 ​

你会看到什么 ​

先做这一件事：看 code 字段 ​

如果你用的是 Gemini 原生路径 ​

现象一：API_KEY_REQUIRED（没带令牌） ​

原因 ​

解决 ​

现象二：INVALID_API_KEY（令牌无效） ​

原因 ​

解决 ​

现象三：余额不足 ​

原因 ​

解决 ​

现象四：403 Forbidden ​

原因 ​

解决 ​

一次性排查脚本 ​

还不行怎么办 ​

相关页面 ​

认证与 401

你会看到什么

先做这一件事：看 `code` 字段

如果你用的是 Gemini 原生路径

现象一：`API_KEY_REQUIRED`（没带令牌）

原因

解决

现象二：`INVALID_API_KEY`（令牌无效）

原因

解决

现象三：`余额不足`

原因

解决

现象四：`403 Forbidden`

原因

解决

一次性排查脚本

还不行怎么办

相关页面