问题现象

用着用着，终端弹出：

API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"Rate limit reached"}}

订阅用户则更常见这样的提示：

Claude usage limit reached. Your limit will reset at 6pm (Asia/Shanghai)

有人等几分钟就好了，有人等到第二天还是不行——因为这两种根本不是同一个问题。

原因分析

429 家族其实有三种长相相似但完全不同的病，先学会分辨再吃药：

区分技巧： 看报错有没有给出重置时间——给了的多半是订阅用量上限，按提示等就行；持续失败、怎么等都不放行的，要怀疑是支出上限。速率限制最温和，歇一口气就过去。

另外记住一个原则：429 是"你这边的额度/频率问题"，和 529（服务端过载）完全两码事，处理方式南辕北辙。

解决步骤

第一步：/status先看清自己的身份和状态

确认当前登录的是哪个账号、哪种计费方式。很多人 429 的真实原因是：终端里登录的根本不是自己以为的那个账号（比如之前配过别的 Key 或中转，忘了切回来）。

第二步：按报错里的重置时间等

订阅用量上限类的 429，提示里直接写了重置时间（例如 6pm）。这种没有任何绕过的办法，到点自动恢复，安心等即可。

第三步：速率限制类——降频率、减并发

如果是每分钟请求/token 超标：

• 关掉同时开着的其他 Claude Code 会话，别多窗口并行
• 大任务拆小，减少一次任务里连环的工具调用
• 退掉用不到的 MCP 服务器，很多 MCP 会后台产生额外请求

第四步：给子代理换个便宜的小模型

子代理（subagent）干的活往往不需要主力大模型。用环境变量把它们指到更轻的模型上，速率和额度都能省一大截：

第五步：持续失败 → 检查是不是支出上限

怎么等都 429、且报错里没有重置时间的，去控制台检查账户的月度支出上限（spend cap）设置。这种 429 不会自愈，需要调高上限或等额度周期重置。

验证是否恢复

等待或调整后，发一条简单消息测试；订阅类可以临近重置时间后再试。同时可以用 /status 再确认一遍账号状态没跑偏。

知识扩展

Claude Code 报错自救手册：429 过载、401 鉴权、529 限流解决详解

适用人群：日常使用 Claude Code 的开发者，无论你是直连官方 API、订阅 Pro/Max 套餐，还是通过中转/第三方服务接入。

Claude Code 报错全景图

这部分是全文的核心。收藏这张总表，遇到报错先对号入座：

下面逐个展开。

401 Unauthorized：认证失败

典型报错：

常见原因：

1. API Key 复制时少了字符、多了空格（最常见！）
2. Key 已被删除或禁用
3. 环境变量里残留旧 Key，覆盖了新配置
4. 把 A 平台的 Key 配到了 B 平台的 Base URL 上（Key 和端点不匹配）

解决方案：

curl 能通但 Claude Code 不通 → 问题在 Claude Code 的本地配置；curl 也 401 → Key 本身有问题，去后台重新生成。

403 Forbidden：权限不足

典型报错：

常见原因：

1. 账号欠费、被封禁或被风控
2. 服务地区限制：服务商仅对部分地区开放服务，账号注册地区不在支持范围内会被拒绝
3. 中转商那边把你的 Key 权限降了或停了
4. 组织/Workspace 层面的权限策略限制

解决方案：

• 登录对应平台后台检查账号状态和余额
• 确认账号的注册地区在服务商官方支持范围内（以服务商官网公布的地区列表为准）
• 中转用户直接问客服：Key 是否被限速/封禁
• 团队场景：确认你的 Key 有目标 Workspace 的访问权限

合规提示：请确保你的账号注册和使用方式符合服务商的《服务条款》及所在地相关法律法规。

404 Not Found：地址或模型名错了

典型报错：

常见原因：

1. 模型名拼错，或用了旧模型名（模型迭代很快，老名字会下线）
2. Base URL 路径不对：中转 API 常见坑——有的要带 /v1，有的不能带，差一个斜杠就 404
3. 中转商根本不支持你请求的模型

解决方案：

经验法则：模型名一律从服务商后台/文档复制，永远不要凭记忆手打。

429：限流与过载（本文主角）

前面第一章已经详细拆解了 429 的两张面孔，这里补充**你自己的限流（rate_limit_error）**该怎么系统解决：

典型报错：

限流的三个维度（官方 API）：

解决方案（按优先级）：

1. 等重置：429 响应里通常带 retry-after 头，告诉你几秒后恢复
2. 降并发：CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 调低，少用子代理并行
3. 切小模型：批量任务用 Haiku/Sonnet
4. 申请提额：官方控制台里，当用量超过当前限额 50% 后可以自助申请提升层级（Start → Build → Scale）
5. 中转用户：换高等级套餐或换服务商——低价中转的限流是结构性问题，优化姿势救不了

500 / 502 / 503 / 504：服务端错误与超时

典型报错：

定性：这些都是服务端问题，和你的配置无关。但 504 超时有一个例外：任务本身太大（比如让模型一次性输出几万字、处理超大文件），处理时间超过了网关超时阈值。

解决方案：

• 500/502/503：查状态页 → 等几分钟 → 重试。Claude Code 本身也会自动重试这类错误
• 504/timeout：
  • 把大任务拆成小步骤（“先写大纲"→"再逐章展开”）
  • 限制单次输出长度
  • 网络层超时则检查本地网络稳定性

529 overloaded_error：官方过载专属码

典型报错：

这是 Anthropic 官方专门为"容量紧张"设的状态码，和 429 的核心区别是：429 针对你的账号，529 针对所有人。

解决方案：

1. 打开 status.claude.com 确认是否有进行中的事故
2. 有事故 → 等，别改任何配置
3. 无事故但仍报 529 → 慢速重试（间隔 30 秒以上），或 /model 切换模型继续干活
4. 持续数小时 → 收集 request_id 和报错原文提工单

一个重要提醒：有用户反馈遇到限流/过载报错时套餐用量（usage）也莫名被扣，如果你怀疑遇到了这个 bug，保留好时间线和截图去官方 GitHub 仓库（anthropics/claude-code）提 Issue。

Credit balance is too low：余额耗尽

典型报错：

定性：这不是技术问题，是钱包问题——你的 Console 组织预付费额度用完了。

解决方案：

1. 去 platform.claude.com/settings/billing 充值，建议开启自动充值（余额低于阈值自动补），避免半夜干活被打断
2. 如果你有 Pro/Max/Team 订阅，用 /login 切换到订阅认证，就不用烧 API 余额了
3. 团队场景：在 Console 里给每个 Workspace 设置支出上限，防止一个项目烧光全组织的余额

网络类错误：ECONNRESET / ETIMEDOUT / fetch failed

典型报错：

定性：请求根本没到服务端，或者半路断了。常见原因是本地网络不稳定、DNS 解析异常，或者公司网络的防火墙/安全软件拦截了请求。

解决方案：

经验法则：fetch failed 类错误先看本地网络，再看 DNS，最后才怀疑服务商。

Prompt is too long：上下文爆了

典型报错：

定性：会话上下文超过模型上下文窗口上限。长时间连续开发的会话几乎必遇。

解决方案：

• /compact —— 压缩当前会话历史，保留关键信息（首选，不丢上下文主线）
• /clear —— 彻底清空会话重开（适合任务已经切换的场景）
• 把大文件内容写进磁盘文件，让 Claude Code 按需读取，而不是全贴进对话
• 善用 CLAUDE.md 存放长期项目记忆，减少每次对话的重复铺垫

常见问题

Q：429 会被封号吗？

不会。限流是正常的保护机制，等一等或降速就恢复，和违规封禁是两回事。

Q：我一直很轻度使用，为什么也 429？

大概率是多会话/多 MCP 在后台放大了实际请求量，或者登录身份不对。先 /status 核对账号，再检查有没有忘了关的并行会话。

Q：529 和 429 怎么快速区分？

529 overloaded = 服务端挤爆了，等或换模型；429 rate limit = 你这边的频率/额度到顶了，降速或等重置。看状态码第一位后面的数字就行。

总结

429 是所有报错里最需要"先诊断再治疗"的一个：速率限制就降速，用量上限就等重置，支出上限就调额度。下次再看到 Rate limit reached，先 /status 对身份、再看报错有没有重置时间，两分钟就能定位是哪一种。