Claude Code 出现 API Error: Rate limit reached 时，不要先猜“是不是 Pro 不够用”。截至 2026 年 5 月 8 日，正确排查顺序是：确认当前认证 route，查看产品给出的 reset/usage 信息，判断是不是 API Key 或云厂商限流，再检查上下文是否过大、工具调用是否太密、是否存在误报状态。不同 owner 的修复完全不同。
快速答案
- 如果你用 Claude 账号或 Enterprise 登录，先看账号、组织或 Claude Code 界面显示的用量窗口和 reset 时间。
- 如果你用 API Key，运行
/cost，再看 Claude Console、Bedrock、Vertex 或 Microsoft Foundry 的当前 rate limit、spend limit 和retry-after。 - 如果任务很大，先用
/compact、/clear、更精确的文件范围和更轻模型减少上下文压力。 - 如果用量页面还有明显余量但每条命令都被拒绝，先刷新凭据、重启会话、检查后台进程，再准备证据提交给当前支持渠道。
先确认谁拥有这个限制
Claude Code 至少有三类限制面。第一类是 Claude 账号或 Enterprise 的交互用量窗口；第二类是 API Key 所属项目、组织或云厂商 route 的请求/Token/费用限制；第三类是本地会话状态，比如过长上下文、后台进程、旧凭据或工具重试循环。
先运行：
bash/model /cost claude --version
/model 告诉你当前账号实际暴露了哪些模型 route。/cost 只对 API 计费路径有意义。claude --version 用于后续判断问题是否可能和 CLI 版本有关。不要用旧文章里的“每周小时数”“固定价格表”或别人账号的截图替代你自己的当前界面。
立即恢复工作
切换到当前可用的轻量 route。 在 Claude Code 里用 /model 查看可选项。简单编辑、格式化、语法问题和短解释不需要最重模型；把更强 route 留给多文件重构、安全审查和架构决策。
清理上下文。 如果刚刚完成一个任务，直接 /clear 开新上下文。若还需要保留长线程里的关键信息，先 /compact，再继续。不要把一个旧会话无限延长到完全不同的任务。
缩小文件范围。 把“帮我审查整个项目”改成“只看 src/auth/** 和 src/middleware.ts”。Claude Code 的工具调用会把文件内容、命令输出和历史上下文带进后续请求，范围越大，越容易撞到用量或 Token 限制。
尊重 API 的 retry-after。 如果你走 API Key 或云厂商 route，429 响应里的 retry-after、rate-limit headers 和 provider dashboard 比任何博客数字都可靠。短时间重复请求只会浪费额度并延长恢复。
为什么短会话也会触发限制
Claude 网页聊天通常更接近一次问答。Claude Code 是 agentic 工具系统，会读文件、搜索、执行命令、写入代码、运行测试，并把工具输出带回模型。一次用户可见的命令，背后可能包含多个工具步骤和模型请求。
所以真正的问题不是“我用了多少分钟”，而是“这个会话带了多少上下文、读了多少文件、产生了多少工具输出、失败重试了多少次”。大 CLAUDE.md、宽泛搜索、长测试日志、重复失败、多个 agent 并发和跨任务延续旧线程，都会让后续每次请求变重。
降低用量的做法
保持 CLAUDE.md 精简稳定。 把长期规则、构建命令和项目边界写清楚，但不要把大量临时日志或一次性分析塞进去。如果当前 Anthropic route 支持 prompt caching，也要按官方文档确认缓存和 ITPM 的当前合同，不要把旧倍率当成容量规划依据。
合并相关问题。 五个连续小问题会重复携带上下文。把它们合成一个结构化请求，通常比连续追问更省。
把大型输出留在本地。 测试失败时先截取关键错误，不要把完整日志一次性丢回 Claude Code。长解释可以保存到本地文档，下次引用文件，而不是让模型重新分析一遍。
按任务风险选 route。 用轻量 route 做低风险编辑和摘要，用更强 route 处理需要推理深度的变更。可用模型、价格和限制都以当前账号界面为准。
误报和边缘情况
不是每次 Rate limit reached 都是真正额度耗尽。判断误报时不要只凭感觉，准备证据：
- CLI 版本和认证 route
/model输出/cost输出（如果是 API 路径）- 账号或组织用量/重置界面
- 完整错误消息和发生时间
- 重新登录、重启会话、换机器后是否复现
如果当前用量和 reset 界面支持这个限制，就按上面的降模型、清上下文、等待窗口恢复处理。如果它们明显不支持这个限制，再搜索当前 Claude Code issue tracker 或联系 Anthropic 支持。
等待恢复时做什么
等待窗口恢复时，不要把所有工作停掉。可以先写测试、整理复现步骤、拆分下一批任务、减少失败日志、更新文档、手动 review PR，或准备一个干净的上下文包，等 reset 后一次性处理。
如果临时改用其他 coding tool，先确认它的当前配额、模型 route、数据策略和计费方式，不要把生产代码直接交给一个未经验证的备选工具。
FAQ
Claude Code 限制多久恢复？
看拥有这个限制的 surface。Claude Code 或账号页面显示 reset 时间时，以那里为准；API 路径看 headers、Console 或云厂商 dashboard；Enterprise 看组织和管理员设置。
是否应该升级 Pro 或 Max？
只有在你已经清理上下文、合理切换模型、排除误报后仍经常被真实用量窗口阻塞，才值得评估升级。用当前账号里的价格、你的实际停工成本、API 计费或 Enterprise 管控需求做判断。
Claude Code 为什么比聊天更容易触发用量压力？
因为 Claude Code 会执行工具调用。文件读取、搜索、命令执行、写入和测试输出都会增加上下文和请求量；网页聊天通常只是直接问答。