错误代码对照表

按现象查，不是按错误码查。每条都给出「为什么」和「怎么办」。

报错前先做这一步

把响应头里的 X-Oneapi-Request-Id 抄下来。找客服时带上它，能直接定位到那一条日志，比描述半天有用。

命令行里看：curl -i ... 或 curl -D - -o /dev/null ...

401 未授权

`无效的令牌`

最常见的错误，原因按概率排序：

原因	怎么确认
复制时带了空格或换行	`echo -n "$ANTHROPIC_AUTH_TOKEN" \| wc -c` 看长度对不对
令牌已被删除	去令牌页看还在不在
环境变量没生效	`echo $ANTHROPIC_AUTH_TOKEN` 确认；改了 rc 文件要 `exec $SHELL`
用错了变量名	Claude Code 用 `ANTHROPIC_AUTH_TOKEN`；Codex 用你在 `env_key` 里指定的名字
客户端配置文件覆盖了环境变量	`~/.claude/settings.json` 里的 `env` 优先级更高

一条命令确认是不是令牌本身的问题：

bash

curl -s https://api.52pay.com/v1/models \
  -H "Authorization: Bearer <您的令牌>" | head -c 300

返回模型列表 = 令牌没问题，去查客户端配置。

`未提供令牌`

请求里根本没带认证头。检查客户端有没有把 API Key 填进去，或者 Base URL 填错导致请求打到了不需要认证的路由上。

`该令牌已过期`

建令牌时设了过期时间。去令牌页改成「永不过期」，或者新建一把。

`该令牌额度已用尽`

这把令牌单独设了额度上限并跑完了。改成「无限额度」或调高上限。

注意区分「令牌额度」和「账号余额」

令牌额度用尽 → 这一把令牌的上限到了，账号里可能还有钱
额度不足 → 账号余额没了，所有令牌都不能用

前者去令牌页改，后者去充值。

`该令牌状态不可用` / `该用户已被禁用`

令牌或账号被停用了。联系客服。

403 禁止访问

`您的 IP 不在令牌允许访问的列表中`

建令牌时填了 IP 白名单，而当前出口 IP 不在里面。

bash

# 查自己的出口 IP
curl -s https://ipinfo.io/ip

家宽 IP 会变，服务器换了机房 IP 也会变。要么把新 IP 加进白名单，要么清空该限制。

`该令牌无权访问模型 xxx`

建令牌时设了模型限制。去令牌页把该模型加进允许列表，或者清空限制。

`无权访问 xxx 分组`

你的账号等级不支持该分组。换 default 分组，或联系客服。

404 未找到

几乎全是 Base URL 写错。

客户端	正确写法	错误写法
Claude Code	`https://api.52pay.com`	~~`https://api.52pay.com/v1`~~
Codex CLI	`https://api.52pay.com/v1`	~~`https://api.52pay.com`~~
Cursor / Cline (OpenAI)	`https://api.52pay.com/v1`	~~`https://api.52pay.com`~~
Cline (Anthropic)	`https://api.52pay.com`	~~`https://api.52pay.com/v1`~~
Gemini CLI	`https://api.52pay.com`	~~`https://api.52pay.com/v1beta`~~
Cherry / NextChat	多数会自动补 `/v1`，填域名即可	填了 `/v1` 反而 404

规律：客户端如果自己会拼 /v1/messages、/v1/chat/completions 这样的完整路径，你就只填域名；如果它拼的是 /chat/completions 这样的相对路径，你就要带 /v1。

返回的是一坨 HTML 而不是 JSON

同一个问题的另一种表现——请求打到了网页路由上。检查 Base URL。

`model not found` / `模型不存在`

模型 ID 拼错了。去价格页复制准确的 ID，注意：

claude-haiku-4-5-20251001 带日期后缀，不能简写成 claude-haiku-4-5
gemini-3-pro-preview 带 -preview
大小写敏感

或者用接口拉一份当前可用列表：

bash

curl https://api.52pay.com/v1/models -H "Authorization: Bearer <您的令牌>"

429 限速

`您已达到请求数限制：N分钟内最多请求M次`

触发了站点的调用频率限制。处理：

降低并发——同时跑 10 个 Agent 很容易撞上限
加退避重试——失败后等 2s、4s、8s 再试，不要立刻重试
长期高频需求联系客服调整限额

`您已达到总请求数限制：...包括失败次数，请检查您的请求是否正确`

这条特别提示失败也算次数。如果你的脚本在疯狂重试一个必然失败的请求（比如模型名写错），会很快撞上这个限制。

先把请求改对，不要靠重试硬扛。

上游返回的 429

上游供应商的限速。通常几秒后自动恢复。持续出现说明该线路饱和，换个分组试试。

500 / 502 / 504 服务端错误

现象	处理
偶发 500	直接重试，通常是上游抖动
持续 502	网关或上游不可用，等几分钟或换分组
504 超时	请求太大或上游太慢，见下面的超时

这类错误如果持续 5 分钟以上，带上 X-Oneapi-Request-Id 找客服。

503 无可用渠道

`分组 X 下模型 Y 无可用渠道`

意思是：你令牌所属的分组里，没有配置能跑这个模型的线路。

按顺序排查：

模型名对不对——去价格页核对
这个分组开放了这个模型吗——价格页上每个模型都标了可用分组
换个分组——default 分组覆盖全部模型，先用它试

bash

# 直接看当前令牌能用什么
curl https://api.52pay.com/v1/models -H "Authorization: Bearer <您的令牌>"

这个列表里没有的模型，就是你这把令牌调不了的。

`当前分组上游负载已饱和，请稍后再试`

线路满了。处理：

等 30 秒重试
换专用分组（Claude Code Max、Openai、Gemini 等）
换个模型档位（Opus 满了试试 Sonnet）

`渠道亲和性命中的渠道已被禁用，已按规则停止重试`

你的会话之前绑定的那条线路出问题被自动下线了，为了避免上下文错乱系统没有自动换线。

处理：开一个新会话（Claude Code 里 /clear），会重新分配线路。

额度问题

`额度不足` / `用户额度不足`

账号余额用完了。去充值。

预扣费失败：`预扣费额度失败, 用户剩余额度: X, 需要预扣费额度: Y`

发起请求时余额不够覆盖预估消耗。大上下文请求预估值会很高，即使实际消耗没那么多也会被拦。

处理：充值，或者减小请求体积（max_tokens 调小、上下文裁剪）。

流式无输出 / 一直转圈

发出去了，但一个字都不出，或者卡很久才一次性吐出来。

按可能性排查：

1. 本地网络中间件缓冲了 SSE

公司代理、某些 VPN、本地抓包工具会缓冲流式响应。

确认方法：直接 curl 看能不能实时出字：

bash

curl -N https://api.52pay.com/v1/chat/completions \
  -H "Authorization: Bearer <您的令牌>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"数到20"}],"stream":true}'

curl 能实时出字、客户端不行 → 问题在客户端或它走的代理。

2. 模型在思考

推理模型（*-thinking、gpt-5.x 高推理强度、Gemini 的 thinking）会先思考很久再输出。这是正常的，不是卡住。

Codex 里把 model_reasoning_effort 降到 low 会明显变快。

3. 请求太大

几十万 token 的上下文，光是上传和处理就要几十秒。/clear 或 /compact 之后重试。

4. 客户端超时设置太短

Claude Code：

json

{ "env": { "API_TIMEOUT_MS": "600000" } }

Codex：

toml

[model_providers.kmt]
stream_idle_timeout_ms = 600000

retry 死循环

客户端反复显示 retrying... 但永远不成功。

根因几乎都是「一个必然失败的请求被无限重试」。常见触发：

底层错误	表现	解法
模型名写错	一直 retry	改成正确的模型 ID
分组没有该模型	一直 retry	换分组或换模型
余额不足	一直 retry	充值
请求体超限	一直 retry	减小上下文

怎么看到真正的错误：

bash

claude --debug            # Claude Code
RUST_LOG=debug codex ...  # Codex

或者直接去控制台日志看那几条失败记录的错误信息。

重试次数别调高

每次重试都是一次独立计费的请求。设成 10 次，一个必然失败的请求会把钱花 10 遍。 遇到 retry 循环，先停下来查原因，不要加大重试。

请求超时

场景	处理
大上下文（>200K token）	正常会慢，放宽客户端超时
高推理强度	降低 `reasoning_effort` / `thinking.budget_tokens`
图像生成	生图本身就要 10–60 秒，耐心等
网络不稳	换网络试试；国内直连不需要 VPN，开着 VPN 反而可能更慢

工具调用异常

模型该调工具时不调，或者参数乱填。

原因	处理
模型本身工具能力弱	换 `claude-sonnet-4-6` / `claude-opus-4-8` / `gpt-5.4`，这几个最稳
走了协议转换	Claude 系模型改用 Anthropic 原生协议，语义更完整
工具定义太多	MCP server 装太多，精简一下
工具描述写得含糊	把「什么时候该用这个工具」写清楚

缓存不命中

cache_read_input_tokens 一直是 0。

原因	处理
`CLAUDE.md` / 规则文件频繁改动	稳定下来别改
MCP server 增删	工具定义变了，前缀就变了
每次都开新会话	缓存有生存期，冷启动必然不命中
用的不是 Claude 系模型	各家缓存机制不同，缓存倍率见模型与分组
前缀内容里有时间戳等变量	把变化的内容挪到后面

详见成本优化策略 → Prompt Cache。

还是没解决？

联系站内在线客服，带上这四样：

X-Oneapi-Request-Id（响应头里）
完整的错误信息（原文，不要转述）
客户端名称 + 版本 + 你填的 Base URL
模型 ID 和令牌所属分组

有了这些，通常一轮就能定位。只说「用不了」的话，客服也只能反问你上面这四件事。

错误代码对照表 ​

401 未授权 ​

无效的令牌 ​

未提供令牌 ​

该令牌已过期 ​

该令牌额度已用尽 ​

该令牌状态不可用 / 该用户已被禁用 ​

403 禁止访问 ​

您的 IP 不在令牌允许访问的列表中 ​

该令牌无权访问模型 xxx ​

无权访问 xxx 分组 ​

404 未找到 ​

返回的是一坨 HTML 而不是 JSON ​

model not found / 模型不存在 ​

429 限速 ​

您已达到请求数限制：N分钟内最多请求M次 ​

您已达到总请求数限制：...包括失败次数，请检查您的请求是否正确 ​

上游返回的 429 ​

500 / 502 / 504 服务端错误 ​

503 无可用渠道 ​

分组 X 下模型 Y 无可用渠道 ​

当前分组上游负载已饱和，请稍后再试 ​

渠道亲和性命中的渠道已被禁用，已按规则停止重试 ​

额度问题 ​

额度不足 / 用户额度不足 ​

预扣费失败：预扣费额度失败, 用户剩余额度: X, 需要预扣费额度: Y ​

流式无输出 / 一直转圈 ​

1. 本地网络中间件缓冲了 SSE ​

2. 模型在思考 ​

3. 请求太大 ​

4. 客户端超时设置太短 ​

retry 死循环 ​

请求超时 ​

工具调用异常 ​

缓存不命中 ​

还是没解决？ ​

错误代码对照表

401 未授权

`无效的令牌`

`未提供令牌`

`该令牌已过期`

`该令牌额度已用尽`

`该令牌状态不可用` / `该用户已被禁用`

403 禁止访问

`您的 IP 不在令牌允许访问的列表中`

`该令牌无权访问模型 xxx`

`无权访问 xxx 分组`

404 未找到

返回的是一坨 HTML 而不是 JSON

`model not found` / `模型不存在`

429 限速

`您已达到请求数限制：N分钟内最多请求M次`

`您已达到总请求数限制：...包括失败次数，请检查您的请求是否正确`

上游返回的 429

500 / 502 / 504 服务端错误

503 无可用渠道

`分组 X 下模型 Y 无可用渠道`

`当前分组上游负载已饱和，请稍后再试`

`渠道亲和性命中的渠道已被禁用，已按规则停止重试`

额度问题

`额度不足` / `用户额度不足`

预扣费失败：`预扣费额度失败, 用户剩余额度: X, 需要预扣费额度: Y`

流式无输出 / 一直转圈

1. 本地网络中间件缓冲了 SSE

2. 模型在思考

3. 请求太大

4. 客户端超时设置太短

retry 死循环

请求超时

工具调用异常

缓存不命中

还是没解决？