错误码对照
按 HTTP 状态码查：这个码是什么意思、通常是谁的错、下一步做什么。
先看这一条
HTTP 状态码只说明「哪一类问题」，不说明「具体哪个原因」。 同一个 401，可能是 Key 写错了，也可能是余额为 0。 所以下表给的是排查方向，具体到某一条报错，请按「相关 FAQ」那一列进去看。
你能自己看到错误请求记录
控制台里可以查看你自己的错误请求记录，包括失败原因。 比对着猜快得多 —— 排查任何报错时都可以先去看一眼。
状态码表
| 状态码 | 含义 | 常见原因 | 怎么修 | 相关 FAQ |
|---|---|---|---|---|
| 400 | 请求格式不对 | 请求体不是合法 JSON；model 字段缺失；必填参数没给；max_tokens 之类的值越界；流式与非流式参数混用 | 拿官网文档的最小请求体重发一次，逐项加参数定位 | Claude Code · Codex · Gemini |
| 401 | 没通过鉴权 | 令牌写错/被删除/已过期；请求头格式不对（少了 Bearer 、字段名拼错）；余额为 0；拿别家的 Key 来用；把 Anthropic 的填法用在 OpenAI 端点 | 按认证与 401的三步走 | 认证与 401 |
| 403 | 有身份，但没权限 | 令牌的 IP 白名单不匹配；令牌设了模型限制而请求的模型不在其中；账号或地区受限 | 检查令牌的 IP 白名单与模型限制；地区限制见支持的国家和地区 | 认证与 401 |
| 404 | 路径不存在 | 最常见的三种：OpenAI 端点少了 /v1；Anthropic 端点多写了 /v1（变成 /v1/v1/messages）；路径拼错。响应体是纯文本 404 page not found，见下节 | 对照接口总览里的「/v1 该怎么给」表逐一核对 | 接口总览 · 连接与超时 |
| 429 | 请求被限流 | 并发太高或短时间内请求过于密集；福利/轻享档渠道本身容量有限，高峰期容易触发 | 降低并发、加重试与退避；把关键任务换到 稳享/尊享 档分组 | 连接与超时 · 怎么选分组 |
| 500 | 服务端内部错误 | 网关或上游渠道处理异常 | 先重试一次；持续出现就去看服务状态页，并换分组试 | 连接与超时 |
| 502 | 上游返回了无效响应 | 上游渠道异常、被上游拒绝、渠道正在切换 | 换分组或换端点重试；看服务状态页确认范围 | 连接与超时 |
| 504 | 上游响应超时 | 请求已发出但上游没在时限内回；长文本、生图、高负载时段更容易出现 | 缩短输入或改用流式；换分组；看状态页 | 连接与超时 |
关于 模型不存在
模型不存在 不在这张表里，因为它不是一个固定的 HTTP 状态码 —— 不同客户端把它显示成 400 或 404，措辞也各不相同。
但它是全站最高频的报错，原因几乎总是同一个：令牌的分组不包含你要的模型。
→ 完整排查见模型不存在 / 分组选错
关于 401：看 code 就能分清是哪一种
401 是最值得背下来的一类。它的两种成因，code 字段完全不同， 所以你可以靠这一个字段把排查范围砍掉一半：
| 场景 | code | 说明 |
|---|---|---|
| 根本没带令牌 | API_KEY_REQUIRED | 请求头里没有可用凭据 —— 多半是配置没生效 |
| 带了但无效 | INVALID_API_KEY | 令牌写错、已删除、已过期，或是别家平台的令牌 |
实测原文如下。
缺少鉴权头（API_KEY_REQUIRED）：
{
"code": "API_KEY_REQUIRED",
"message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}令牌无效（INVALID_API_KEY）：
{ "code": "INVALID_API_KEY", "message": "Invalid API key" }这条 message 本身就告诉你该往哪写
API_KEY_REQUIRED 的文案里列明了平台接受的三种鉴权头： Authorization: Bearer、x-api-key、x-goog-api-key。 照这三者之一去检查你的请求头，不用猜。
走 Gemini 原生路径（/v1beta/...）时，401 是 Gemini 风格的结构，格式和上面两种不一样：
{
"error": {
"code": 401,
"message": "API key is required",
"status": "UNAUTHENTICATED"
}
}令牌无效时 message 变成 Invalid API key，status 仍是 UNAUTHENTICATED。
写客户端错误处理时要注意
OpenAI 与 Anthropic 兼容路径返回 {code, message}； Gemini 原生路径返回 {error: {code, message, status}}。 如果你的程序要解析错误信息，这两套结构得分开判断。
关于 404：响应体不是 JSON
漏写 /v1 的典型表现，是一个纯文本的 404，不是 JSON：
curl -X POST https://cn.fluxtoken.ai/chat/completions
# HTTP 404，响应体：
# 404 page not found看到非 JSON 的 404 page not found，就应该立刻想到「路径问题」—— 而不是去怀疑令牌、余额或分组。这几样出问题时返回的都是 JSON。
对照表：
| 路径 | 状态码 | 说明 |
|---|---|---|
/v1/models | 401 | 存在，需鉴权 |
/v1/chat/completions | 404（漏写 /v1 时） | 落到网页路由上，返回纯文本 |
/v1/messages | 401 | 存在，需鉴权（Anthropic 协议） |
/v1beta/models | 401 | 存在，需鉴权（Gemini 风格） |
未实测的部分
上表与上文引用的报错文案，都是直接对生产端点发起请求抓到的真实响应。
以下情形文档不给出精确文案，因为措辞会随上游渠道变化：
- 余额不足的具体报错字符串
- 分组不含该模型时
模型不存在的精确响应体 - 速率限制（
429）的响应体 - 上游错误的透传格式
宁可写得笼统，也不要照着假 JSON 去比对
上面这几类错误以线上实际返回为准。文档只给出「返回什么状态码、属于什么问题、 该怎么修」这一层，不逐字引用可能对不上的文案。
排查顺序
遇到任何报错，按这个顺序走，通常两步内能定位：
- 看服务状态页 https://status.fluxtoken.ai/ —— 确认是不是整个分组都在波动。是波动就等，不是故障
- 核对端点与
/v1—— 见接口总览的对照表。这一条解决的问题比想象中多 - 核对模型名与分组 —— 模型名逐字对照模型列表，分组对照怎么选分组
- 核对令牌 —— 令牌管理里确认令牌还在、没过期、分组对、余额够
- 看控制台的错误请求记录 —— 里面有失败原因
- 换分组试一次 —— 能通说明是渠道问题，不是你的配置问题
- 还不行 → 带着请求 ID、时间、模型名、报错原文进群
还不行怎么办
- 服务状态页：https://status.fluxtoken.ai/
- 报错原文总索引：报错原文索引
- QQ 群
1108757955· Telegram https://t.me/fluxtokengroup
提问时附上：发生时间、模型名、分组名、完整报错原文、请求 ID。这几项齐全，群里基本能当场判断。