用 Claude Code、Cursor 这类 AI 编程工具,或者直接调大模型 API,最常碰到的两个报错是 401 和 429。很多人一看报错就懵,以为是「网络不好」或者「账号被封」,然后去换网络、重装客户端,结果没用。
(实测)这两个错误码的含义完全不一样,对症下药才行:
401 Unauthorized(未授权):你的 API Key 不对或失效。要么 key 打错了,要么 key 过期了、被删了、或者额度用完了被停用。这是「身份认证」问题,跟网络无关。429 Too Many Requests(请求太多):你的请求频率/额度超了。要么短时间内请求太密集触发了限流,要么账户的配额(token 额度、请求次数)用完了。这是「限流」问题,跟 key 对不对无关。一句话:401 查 key,429 查额度/频率。 方向搞反了,就会在错误的地方反复折腾,白耗时间还解决不了问题。
我自己有次调一个大模型 API,一直报 401。第一反应是「网络问题」,挂了代理、换了节点,还是 401;又怀疑客户端坏了,重装了一遍,依然 401。
后来静下心看报错详情,才发现是 API Key 后面多复制了一个空格——我从网页上复制 key 的时候,不小心带上了行尾的换行或空格,导致发出去的 key 实际是 sk-xxxxxx(后面多了个空格),服务端校验不通过,就报 401。
(实测)把 key 前后多余的空格、换行删掉,重新填,立刻就通了。这个教训很典型:401 先别怀疑网络和客户端,先怀疑 key 本身——是不是复制错了、多带了空格、用了旧的已删除的 key。
顺带说一句,那次之后我养成了一个习惯:拿到新 key,先 curl 裸调一次确认它能通,再填进工具里。 这样能一次性排除「key 本身有问题」这个最大的变量,后面工具再报错,就只需要怀疑工具配置,不用回头怀疑 key。这个习惯帮我省掉了大量「在工具里反复折腾 key」的时间。
(实测)401 和 429 只是 HTTP 状态码,真正的信息在报错的完整文本里。不同平台给的信息不一样:
Invalid API key(key 无效)、API key expired(key 过期)、Insufficient quota(额度不足)、Rate limit exceeded(限流)。401 或 429 加一段话。先把完整报错读一遍,能直接锁定方向。这一步比「看到错误码就猜」快得多,但很多人会跳过。
补一个进阶手段:如果你不确定是哪个环节出问题,可以直接用 curl 裸调一次 API,把问题从「工具」隔离出来,单独验证「key 和网络到底通不通」。
# 用 curl 直接调一次 API,看返回的错误码(以 OpenAI 兼容接口为例)
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer sk-你的key"
# 返回 401 → key 有问题(错/过期/多空格)
# 返回 429 → 额度或限流问题
# 返回 200(正常列表)→ key 和网络都通,问题出在工具配置上
(实测)这一步的价值在于「隔离变量」:如果 curl 能通、但工具报错,说明是工具配置问题(环境变量没生效、代理干扰等);如果 curl 直接 401/429,说明是 key 或额度问题。用 curl 一测,就能把「key 问题」和「工具问题」切开,不用在工具里瞎猜。
如果是 401,按这个顺序查 key:
sk-xxxx 是占位符,别直接复制去用。(来源:各 AI 服务商 API 文档对 401 的统一定义——认证失败)401 的本质是「服务端不认可你的身份」,所以排查永远围绕 key 展开。
如果是 429,查两个东西:
sleep 降速、或做请求排队就能解决。(实测)429 有个容易忽略的点:限流有时是「软限流」,等几分钟再试就好了;有时是「硬额度」,等也没用,必须充钱。判断方法:看报错里有没有「retry after」或「请在 X 秒后重试」之类的提示,有就是软限流(等就行),没有且一直 429 就是额度问题(充钱)。
这里把「限流」再展开说清楚,因为它有三种情况,很多人只知其一:
sleep、并发数调小。(来源:OpenAI、Anthropic 等 API 文档对 rate limit 的分层说明)分清是「频率」还是「余额」,决定了你是「降速」还是「充钱」。判断最快的方法还是回到控制台看用量面板,它会告诉你到底是哪种超了。
Claude Code、Cursor 这类工具,在 401/429 之外还有几个自己的坑:
ANTHROPIC_API_KEY 环境变量,如果你既登录了 Claude 账号又设了环境变量,可能取错。ANTHROPIC_API_KEY 要在启动终端之前设置,或者写进 shell 配置文件。改了环境变量但没重启终端,工具读到的还是旧值。(实测)我遇到过的「Claude Code 一直 401」里,有一半是环境变量没配对(key 对了但没生效),一半是代理干扰。这两个都查过还 401,再回头看 key 本身。
补充一个高频但少人讲的场景:多个工具抢同一个 key 导致互相限流。如果你用同一个 API Key 同时接了 Claude Code、Cursor、还有自己的脚本,三路请求都打向同一个 key,很容易触发那个 key 的 RPM 限流,然后三路一起报 429。解决办法是给不同用途分不同的 key(服务商一般都允许一个账户创建多个 key),或者至少错开使用时间。这也是「429 频繁出现」时一个常被忽略的根因。
(实测)很多人把 403 和 401 混为一谈,但它们是不同的:
所以看到 403,别去查 key 对不对(key 是对的,否则会是 401),要查「你这个账户/这个 key 有没有访问这个模型的权限」。这两者的区别,能帮你少走一步弯路。
把 403 的具体场景也列一下,方便对照:
(实测)403 最容易被误判成「key 错了」,但真相往往是「key 对,只是这个 key 没权限干这件事」。所以看到 403,第一反应应该是「我有没有权限」,而不是「我 key 是不是填错了」。
(实测)调 API 报错时,最容易陷入的误区是「眉毛胡子一把抓」——同时怀疑 key、网络、额度、工具,然后每个都乱试一遍,试到最后自己都乱了。
更好的做法是一次只动一个变量:
curl 裸调,隔离出「key 和网络」到底通不通(前面第二步讲过)。(来源:排查类问题通用的「二分定位」思路)这个「隔离变量 + 按错误码分流」的框架,不光适用于 AI API,任何「调用第三方服务报错」的场景都能套用。掌握了它,你遇到报错就不会慌,而是先冷静地「二分定位」。
该看的:你调大模型 API 或用 Claude Code、Cursor 时,报 401、429、403,不确定是该查网络、查 key、还是查额度的人。按「读完整报错 → 401 查 key → 429 查额度 → 工具特有坑」这个顺序走,绝大多数能定位。
可以换方向的:如果你报的是连接超时、连不上服务器(connection refused、timeout),那不是认证/额度问题,是网络链路问题,要往代理、DNS、防火墙方向查。这个和 401/429 是两套完全不同的病。
最后串一下站内相关的:如果你用的是本地部署的 ollama 而不是云端 API,那报错逻辑完全不同——ollama 连不上是本地端口/服务的问题(Ollama 连不上 11434 端口 connection refused);如果你 ollama 能连但下载模型卡住,又是另一回事(ollama 下载模型太慢卡在 pulling manifest)。
一句话收尾:AI 工具报 401 查 key、报 429 查额度、报 403 查权限、报连接超时查网络——四个错误四个方向,别混着治,方向对了十分钟内能定位。
把这套走完,绝大多数 API 报错都能落到一个明确原因上:key 复制错/过期、额度耗尽、限流、权限不够、或代理干扰。落到原因后对症处理——重填 key、充钱、降速、开权限、关代理——就行。真正需要「换网络、重装系统」才能解决的 API 报错,在我遇到的比例里极低。记住那个「隔离变量」的框架:先用 curl 裸调一次,把「key/网络」和「工具配置」切开,再按错误码分流,别眉毛胡子一把抓。