AI工具报 401、429、403 怎么办?按错误码分流排查(2026)

Updated on in AI 工具

先说结论:AI 工具报 401 和 429,是两个完全不同的病,别一起治

用 Claude Code、Cursor 这类 AI 编程工具,或者直接调大模型 API,最常碰到的两个报错是 401 和 429。很多人一看报错就懵,以为是「网络不好」或者「账号被封」,然后去换网络、重装客户端,结果没用。

(实测)这两个错误码的含义完全不一样,对症下药才行:

  • 401 Unauthorized(未授权):你的 API Key 不对或失效。要么 key 打错了,要么 key 过期了、被删了、或者额度用完了被停用。这是「身份认证」问题,跟网络无关。
  • 429 Too Many Requests(请求太多):你的请求频率/额度超了。要么短时间内请求太密集触发了限流,要么账户的配额(token 额度、请求次数)用完了。这是「限流」问题,跟 key 对不对无关。

一句话:401 查 key,429 查额度/频率。 方向搞反了,就会在错误的地方反复折腾,白耗时间还解决不了问题。

我踩过的坑:一个「换网络、重装都没用」的 401

我自己有次调一个大模型 API,一直报 401。第一反应是「网络问题」,挂了代理、换了节点,还是 401;又怀疑客户端坏了,重装了一遍,依然 401。

后来静下心看报错详情,才发现是 API Key 后面多复制了一个空格——我从网页上复制 key 的时候,不小心带上了行尾的换行或空格,导致发出去的 key 实际是 sk-xxxxxx(后面多了个空格),服务端校验不通过,就报 401。

(实测)把 key 前后多余的空格、换行删掉,重新填,立刻就通了。这个教训很典型:401 先别怀疑网络和客户端,先怀疑 key 本身——是不是复制错了、多带了空格、用了旧的已删除的 key。

顺带说一句,那次之后我养成了一个习惯:拿到新 key,先 curl 裸调一次确认它能通,再填进工具里。 这样能一次性排除「key 本身有问题」这个最大的变量,后面工具再报错,就只需要怀疑工具配置,不用回头怀疑 key。这个习惯帮我省掉了大量「在工具里反复折腾 key」的时间。

按「花多少时间、多大概率解决」排序的排查步骤

第一步:看清楚完整报错,别只看错误码(1 分钟,先定性)

(实测)401 和 429 只是 HTTP 状态码,真正的信息在报错的完整文本里。不同平台给的信息不一样:

  • 有的会明确写 Invalid API key(key 无效)、API key expired(key 过期)、Insufficient quota(额度不足)、Rate limit exceeded(限流)。
  • 有的只给一个状态码,比如 Claude Code 里常见的就是直接报 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(3 分钟)

如果是 401,按这个顺序查 key:

  1. 复制有没有带空格/换行:把 key 粘贴到一个纯文本编辑器(记事本)里,看首尾有没有多余空格或换行,删掉后再填。这是最高频的 401 原因。
  2. key 是不是过期/被删了:去服务商的控制台(比如 Anthropic Console、OpenAI Platform)看这个 key 的状态,是否显示「active」、有没有过期时间。
  3. key 是不是填错位置了:有些工具区分「API Key」和「登录账号」两个概念,别把网页登录的密码填进 API Key 的框里。特别是有些工具既支持「登录账号」又支持「自带 key」,两种模式的入口长得像,很容易填串。
  4. 是不是用了别人的示例 key:网上教程里的 sk-xxxx 是占位符,别直接复制去用。

(来源:各 AI 服务商 API 文档对 401 的统一定义——认证失败)401 的本质是「服务端不认可你的身份」,所以排查永远围绕 key 展开。

第三步:429 的排查——查额度和频率(3 分钟)

如果是 429,查两个东西:

  1. 额度用完没:去控制台看账户余额、token 配额、本月用量。很多免费额度(比如免费试用、赠送的 credits)用完了,就会从「能用」变成「429 或额度不足」。充钱或换付费方案是唯一解。
  2. 请求太密触发限流:如果你在脚本里写了个循环疯狂调 API,或者同时开了好几个工具在抢同一个 key,会触发每分钟/每天的请求上限。加个 sleep 降速、或做请求排队就能解决。

(实测)429 有个容易忽略的点:限流有时是「软限流」,等几分钟再试就好了;有时是「硬额度」,等也没用,必须充钱。判断方法:看报错里有没有「retry after」或「请在 X 秒后重试」之类的提示,有就是软限流(等就行),没有且一直 429 就是额度问题(充钱)。

这里把「限流」再展开说清楚,因为它有三种情况,很多人只知其一:

  1. RPM/TPM 限流:每分钟请求数(Requests Per Minute)或每分钟 token 数(Tokens Per Minute)超了。这是「频率」问题,降低请求密度就能解决——脚本里加 sleep、并发数调小。
  2. 每日额度用尽:很多按量付费账户有「每日上限」或「硬顶」,到了就 429,要等第二天或调高上限。
  3. 账户余额/订阅额度耗尽:预付的 credits 用完了、或订阅的额度用完了,这种情况「等」也没用,只能充值或升级。

(来源:OpenAI、Anthropic 等 API 文档对 rate limit 的分层说明)分清是「频率」还是「余额」,决定了你是「降速」还是「充钱」。判断最快的方法还是回到控制台看用量面板,它会告诉你到底是哪种超了。

第四步:工具特有的坑(2 分钟,Claude Code / Cursor 专属)

Claude Code、Cursor 这类工具,在 401/429 之外还有几个自己的坑:

  1. 登录态 vs API Key 的冲突:Cursor 可以「登录账号用订阅」也可以「填自己的 API Key」,两者如果都配了,可能互相冲突。Claude Code 默认走 ANTHROPIC_API_KEY 环境变量,如果你既登录了 Claude 账号又设了环境变量,可能取错。
  2. 环境变量没生效:Claude Code 里 ANTHROPIC_API_KEY 要在启动终端之前设置,或者写进 shell 配置文件。改了环境变量但没重启终端,工具读到的还是旧值。
  3. 代理干扰:如果你的 API 请求走了代理,而代理节点把请求转发到了错误的地区或加了奇怪的 header,也可能报认证错误。先关代理直连试试,能排除代理的干扰。

(实测)我遇到过的「Claude Code 一直 401」里,有一半是环境变量没配对(key 对了但没生效),一半是代理干扰。这两个都查过还 401,再回头看 key 本身。

补充一个高频但少人讲的场景:多个工具抢同一个 key 导致互相限流。如果你用同一个 API Key 同时接了 Claude Code、Cursor、还有自己的脚本,三路请求都打向同一个 key,很容易触发那个 key 的 RPM 限流,然后三路一起报 429。解决办法是给不同用途分不同的 key(服务商一般都允许一个账户创建多个 key),或者至少错开使用时间。这也是「429 频繁出现」时一个常被忽略的根因。

一个容易混淆的点:403 和 401 不是一回事

(实测)很多人把 403 和 401 混为一谈,但它们是不同的:

  • 401 = 没认证/认证失败:服务端「不认识你是谁」,查 key。
  • 403 = 认证了但没权限:服务端「认识你,但不让你干这件事」。常见于:你的 key 没有某个模型的访问权限、或者账户地区限制(比如某些服务商限制特定地区调用)、或者你请求了一个你订阅方案里不包含的模型。

所以看到 403,别去查 key 对不对(key 是对的,否则会是 401),要查「你这个账户/这个 key 有没有访问这个模型的权限」。这两者的区别,能帮你少走一步弯路。

把 403 的具体场景也列一下,方便对照:

  1. 模型权限未开:有些服务商的新模型需要单独申请权限(比如某些 beta 模型、或高等级的模型),普通账户直接调会 403。去控制台看这个模型是否需要额外开通。
  2. 地区限制:部分服务商的 API 对特定地区有限制(这个因服务商而异,以你用的那个的官方说明为准)。如果你挂了代理、出口 IP 落在受限地区,也可能 403,换个出口试试。
  3. 订阅方案不含这个模型:你的订阅或 key 对应的额度等级,可能不包含你正在调的那个模型。换一个你方案里的模型,或升级方案。

(实测)403 最容易被误判成「key 错了」,但真相往往是「key 对,只是这个 key 没权限干这件事」。所以看到 403,第一反应应该是「我有没有权限」,而不是「我 key 是不是填错了」。

一个通用的排查思维:先「隔离变量」,再「缩小范围」

(实测)调 API 报错时,最容易陷入的误区是「眉毛胡子一把抓」——同时怀疑 key、网络、额度、工具,然后每个都乱试一遍,试到最后自己都乱了。

更好的做法是一次只动一个变量:

  1. 先用 curl 裸调,隔离出「key 和网络」到底通不通(前面第二步讲过)。
  2. 如果 curl 通、工具不通 → 问题在工具配置,去查环境变量、代理、登录态。
  3. 如果 curl 就报错 → 看错误码,401 查 key、429 查额度、403 查权限、超时查网络。

(来源:排查类问题通用的「二分定位」思路)这个「隔离变量 + 按错误码分流」的框架,不光适用于 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/网络」和「工具配置」切开,再按错误码分流,别眉毛胡子一把抓。