API 报错排查大全：401 无效的令牌、额度不足、无可用渠道、404、429、524 怎么解决（附原文）

本页的报错原文来自 api.foo 的线上接口和我们在各工具里的实测（2026 年 10 月 15 日）。其他平台的文字会不一样，但状态码的含义和排查思路是通用的。

速查表

先检查三件事

90% 的报错出在这三处，先逐项核对能省很多时间：

1. 地址：用的是哪个工具，就按它要求的格式填。

   工具	地址填法（以 api.foo 为例）
   Claude Code、Claude 原生 SDK	https://api.foo（不带 /v1）
   Codex、OpenAI 兼容的软件和 SDK	https://api.foo/v1
   Gemini CLI	https://api.foo（不带 /v1beta）

2. 密钥：完整复制，前后没有空格、换行；是这个平台发的密钥，不是别家的。

3. 模型名：和平台模型列表里的写法一字不差，包括大小写、连字符和日期后缀。

401 无效的令牌

{"error":{"code":"","message":"无效的令牌 (request id: …)","type":"new_api_error"}}

请求到了服务商，但服务商不认这把密钥。在 api.foo 上，下面这些情况返回的都是这一句：

• 密钥复制错了、少了字符、多了空格或换行；
• 根本没发出去：环境变量没设成功、配置文件写错了位置、请求头名字写错；
• 密钥已经被你删除或禁用；
• 密钥设置了过期时间，已经过期；
• 这把密钥自己设了额度上限，已经用完（和账户余额是两回事）。

排查办法：

1. 登录控制台，打开 API 密钥，看这把密钥的状态和剩余额度。过期或用完的，延长时间、调高额度，或者新建一把。

2. 用命令行单独测一下密钥（把 sk-你的密钥 换掉）：

   curl https://api.foo/v1/models -H "Authorization: Bearer sk-你的密钥"
   

   返回模型列表说明密钥本身没问题，问题出在你的工具配置上；仍然报「无效的令牌」就是密钥的问题。

3. 用的是环境变量的，新开一个终端运行 echo $变量名，确认真的设上了。

403 权限和余额

模型名不对、无可用渠道

分组 default 下模型 xxx 无可用渠道（distributor）

意思是：在你这个分组里，没有能提供这个模型的通道。按顺序查：

1. 模型名拼对了吗？到平台的模型列表（api.foo 是「模型广场」）复制完整名字，别凭记忆手打。
2. 这把密钥用的是哪个分组？有的模型只在特定分组里有。
3. 平台某个模型暂时下线时也会这样，过一会儿再试或换一个模型。

模型 xxx 的价格尚未由管理员配置，暂时无法使用，请联系站点管理员开启该模型

这是平台还没给这个模型定价、上架，换一个已上架的模型，或联系客服。

未指定模型名称，模型名称不能为空

请求里没带 model 字段，检查工具或代码里的模型设置。

404 Invalid URL

{"error":{"message":"Invalid URL (POST /v1/chat/completion)","type":"invalid_request_error","param":"","code":""}}

报错里括号中的就是你实际请求的路径，对照正确写法改：

429 请求太多

写程序调用时，遇到 429 应该等一会儿再重试，并且每次等得更久一点（指数退避），不要立刻狂刷。官方的 OpenAI、Anthropic SDK 默认就会自动重试几次。

5xx 和 524：上游或网络问题

• 500 / 502 / 503：平台或上游临时出问题。等几十秒重试；持续出现就把报错里的 request id 发给客服。
• 529 overloaded（Claude 特有）：Anthropic 那边过载，稍后重试。
• 524：这是 Cloudflare 返回的超时。请求经过 Cloudflare 时，超过 100 秒还没收到回应就会被断开。常见于非流式的长回答、批量脚本和生成图片。两个办法：
  1. 改用流式输出（stream: true）。Claude Code、Codex 这类工具默认就是流式，一般不会碰到。
  2. 把地址换成不经过 CDN 的直连线路。api.foo 的直连线路是 https://dc.api.foo，只提供 API 接口，没有 100 秒限制。

各个工具里的报错长什么样

同一个「密钥不对」，在不同工具里显示得不一样。下面是我们用同一把错误密钥连 api.foo 时看到的原文，搜报错时可以对照：

工具自己的报错（安装、配置文件格式等）见各工具的教程：

• Claude Code 报错：command not found、安装脚本报错、npm 权限
• Codex 报错：wire_api、profile、TOML 格式
• Gemini CLI 报错：Invalid auth method selected、地区限制
• OpenCode 报错：V1、V2 混用
• CC Switch 常见问题：切换不生效、环境变量冲突

还是解决不了

把下面三样发给客服，问题能最快定位：

1. 报错原文，一定要包含括号里的 request id；
2. 你用的工具和版本，或者代码片段（删掉密钥）；
3. 你填的地址和模型名。

api.foo 的联系方式见关于页。

相关阅读

• API 中转站是什么？怎么选不踩坑
• 大模型 API 是什么？官方平台、云平台、聚合平台怎么选