如果 Claude Code 或一次 Claude API 调用返回 API Error: Rate limit reached，先不要改模型、换 key、充值或加 retry。这个英文错误只是症状，真正决定修复动作的是当前入口：Claude Code 登录会话、API key、provider、Console 额度、模型上下文，还是 Anthropic 的服务状态。
| 报错出现的位置 | 第一项检查 | 可能负责的分支 | 下一步 |
|---|---|---|---|
| Claude Code 终端、VS Code、命令行会话 | /status、当前登录账号、plan、是否有 ANTHROPIC_API_KEY | Claude Code 使用量、订阅登录、API key override、模型上下文 | 保持同一会话，先确认入口，再等待、重新登录或切到明确的 API 路线 |
| SDK、curl、服务端日志里的 HTTP 429 | API key、organization、project、model、headers、Console Limits | Anthropic API 的请求、输入 token、输出 token、项目或模型限制 | 只有看到重置或限额证据时才退避重试，否则修正 scope 或请求形状 |
| 网关、代理、云平台或 provider 返回错误 | provider dashboard、上游错误体、provider request id | provider 额度、wrapper 限流、错误 project、上游 Anthropic 限制 | 先在 provider 侧诊断，不要直接套用官方 API key 修复 |
| Console 显示 credits、billing 或 spend cap 问题 | Credits、billing、usage、spend cap | 账户资金或账单状态 | 停止重试，先处理账户状态 |
| 只在某个模型、长上下文或大输出时报错 | 模型、上下文长度、token 量、并发、fallback 模型 | 模型族或上下文压力 | 缩短上下文、限制输出、降并发或测试小模型 |
| 多个入口同时失败 | Claude Status、时间戳、request id、近期发布变更 | 平台事件或降级 | 保留证据，等待状态恢复，不要盲目换账号 |
判断是否该重试很简单：只有当证据指向请求数或 token 压力，并且你能看到 retry-after、headers、Console、Rate Limits API 或 provider 的重置信号，重试才是修复动作。若证据指向 credits、billing、错误 project、错误 key、Claude Code 使用量、provider 额度或状态事件，继续打同一个请求只会制造噪音。
十分钟恢复顺序
第一分钟先复制完整错误，不只写“rate limit”。保留 HTTP status、error type、error code、request id、endpoint、model、时间戳和时区。Claude Code 里的 terminal 文本、SDK 的 response body、provider 的上游错误体都要分开记录，因为它们证明的是不同入口。
第二步确认当前入口。Claude Code 用 /status 看登录和计费路线；代码调用看实际加载的 API key、organization、project 和 endpoint；provider 调用看 provider project、quota 和 logs。不要同时换模型、换 key、改 retry、改 provider，否则一次成功也不能证明哪个变量真的有效。
第三步看 scope。一个新 key 如果仍属于同一 exhausted project，通常不会修 project 级或 organization 级限制。一个更小模型如果问题来自 billing，也不会修。一个 retry loop 如果问题来自 Claude Code 订阅窗口或 provider 限额，也不会修。每个分支都要有自己的证据。
第四步只做一个最小测试。Claude Code 可以在同一认证会话里跑一个短命令；API 可以用同 key 同 model 发一个小请求；provider 可以走同 provider 的最小负载路线并查看 log。目标不是“多试几次直到碰巧成功”，而是证明当前入口由谁负责。
读懂 API 限额证据
Anthropic 的 API 限额不是一个固定数字。它会涉及请求数、输入 token、输出 token、模型、project、organization 和账户层级。Messages API 场景里，RPM、ITPM 和 OTPM 都要看：短请求可能打到 RPM，少量长上下文请求也可能打到 ITPM 或 OTPM。
当 API key 路线被确认后，实时证据优先级高于复制来的限额表。先看 response headers，再看 Console Limits、Usage、Billing 和 Rate Limits API。不要在文章、工单或内部复盘里写“Claude API 默认多少 RPM 一定这样”，除非那个数字来自当前账户、当前模型和当前时间。
| 证据 | 含义 | 更好的第一修复 |
|---|---|---|
| headers 或 Console 显示请求窗口压力 | 该窗口内请求太密 | jitter backoff、降低并发、按 tenant 排队 |
| 输入或输出 token 压力突出 | 上下文或生成体积太大 | 缩短上下文、限制输出、拆任务、能用时加 prompt caching |
| 只在某个模型或模型族失败 | 模型族共享限制或选型不合适 | 测小模型、降负载、等窗口重置 |
backoff 只适合前两类，而且必须有上限。忽略 headers、token 量和分支归属的 retry 反而会加重限流。客户端如果暴露 retry-after，按它停；没有就用指数退避加 jitter，并限制总尝试次数，让系统明确失败。
把 Claude Code 和 API 限额分开
Claude Code 容易造成误判，因为它看起来像“调用 API”，但可能由订阅登录、API key、provider 凭证或团队环境变量驱动。先跑 /status，再看 ANTHROPIC_API_KEY、shell profile、项目 env、CI secrets 和 provider 配置。不要只凭“我买了 Pro/Max”判断。
如果 /status 显示订阅登录路线，重点检查 Claude Code 使用量、选择的模型、上下文大小、并行 session 和当前会话形状。长 coding session 会带上文件摘要、工具输出和历史上下文；compact、开新会话、减少并行或切小模型都可能是合理测试，但它们不是所有 429 的万能解释。
如果 /status 或环境变量显示 API key 路线，就按 API 问题处理。确认 key 来自哪个 organization/project，确认部署环境是否用了另一份 key，确认 provider 是否包装了上游错误。很多“有余额但还报错”的情况，其实是你看的 Console project 和程序实际用的 project 不是同一个。
不要使用 token 提取、OAuth 绕过或随机代理方案来处理 Claude Code 限制。它们会让入口更难证明，也可能把 secrets 放到不该出现的位置。支持的路径是等待窗口、减负载、修正登录、或者明确切换到可监控的 API 路线。
检查额度、账单和 key 归属
credits、billing 和 spend cap 问题经常被误读为速率限制，因为用户看到的都是请求被拒。修复动作完全不同：账户资金或账单状态异常时，retry 没有意义，必须先改账户状态。
key 归属是第二个常见陷阱。key 属于具体 organization 和 project；provider 也可能有自己的 project、quota、billing 和 throttle。记录归属时不要暴露 key 本身，只记录安全标识：组织名、项目名、provider 名、环境变量来源、部署环境和相关 request id。
订阅和 API 也要分开。Claude Pro/Max 可以影响受支持的 Claude 产品使用和 Claude Code 登录路线，但不会自动变成 API credit 钱包。要判断是否该买 credits，先确认当前报错确实来自 API key 资金或账单分支。
判断 provider、云平台和状态事件
Bedrock、Vertex AI、gateway、hosted app 或内部 proxy 都可能包装 Anthropic 错误，也都可能拥有自己的配额、项目选择、throttle、模型映射和日志。上游错误体有价值，但不能自动证明直接 Anthropic Console 也被限制。
provider 路线先问三件事：provider dashboard 是否有本地 quota 或 billing block；provider log 里是上游 request id 还是只有 provider request id；同一个小请求用直接 Anthropic key 是否也失败。只有这些答案明确后，才决定该处理 provider、Anthropic API，还是应用自己的排队逻辑。
状态事件单独看。多环境同时失败、没有发布变更却突然升高、不同用户同一时间都报错时，打开 Claude Status。状态页异常说明等待比换账号更合理；状态页绿色也不能证明你的 key、project、model、provider 或 Claude Code session 一定正常。
带着证据升级处理
升级时不要只发“rate limit reached”。支持或内部 on-call 需要一个小而完整的证据包：时间戳和时区、完整错误体、HTTP status、request id 或 provider request id、当前入口、model、endpoint、安全的 organization/project 标识、headers、Console 或 provider 限额状态、Claude Status 状态、近期变更，以及确认没有 secrets。
生产侧预防也按同一套入口来设计。API 流量按 tenant 排队，按模型族限制并发，记录 token 量和 request id。Claude Code 团队要明确 session 是订阅登录还是 API key 路线。provider 路线要保存 provider id 和上游 id。账单和 spend cap 要提前监控，而不是等到用户看到 429 才查。
最终目标不是永远不遇到限制，而是遇到限制时能在十分钟内说清楚：哪个入口失败、什么证据证明它、是否允许重试、谁必须改变状态，下一次请求才可能成功。
现场复核清单
如果团队里多人都遇到这个错误，把复核清单固定下来会比临时讨论更可靠。第一行记录入口，第二行记录 credential 来源，第三行记录 model 和上下文，第四行记录实时限额证据，第五行记录是否允许 retry。只要其中一行无法填写，就不要把结论写成“已经确认是 rate limit”。
对 Claude Code 团队来说，复核清单尤其要区分订阅登录和 API key override。一个开发者在本机终端里看到的 /status，不一定等于 CI、远程容器或另一个 shell 的实际 credential。把这些路径分开记录，才能避免同一个修复在本机有效、上线后失效。
把复核清单接入生产时，可以把“是否允许重试”拆成三个答案：允许短退避、必须停止、需要人工升级。允许短退避的条件是 headers 或 Console 明确显示 request/token window；必须停止的条件是账单、credits、wrong project、wrong provider、错误登录或状态事件；需要人工升级的条件是 evidence 不完整但业务影响已经扩大。这样应用不会在不该重试时继续打流量，也不会在一个可恢复窗口里过早报废任务。
日志也要避免泄露 secrets。可以记录 key hash 的安全片段、project 名称、provider 名称、model、request id、token 量和 retry decision，但不要记录完整 API key、bearer token、session token、私有 prompt、客户输入或支付信息。排障材料足够具体，才不需要靠复制敏感数据来解释问题。
如果这类错误已经影响多人协作，把 Claude Code 和 API 调用分开设监控。Claude Code 侧关注 session 数、context 大小、选择的 model、是否意外加载 API key；API 侧关注 RPM、ITPM、OTPM、per-tenant queue、credits、spend cap、provider quota 和 status 变化。两套监控共用一个 incident timeline，但不要共用同一个“限速”结论。
常见问题
看到 API Error: Rate limit reached 可以马上重试吗？
只有当证据显示请求或 token 压力，并且有 reset、header、Console 或 provider 信号时才重试。若问题来自 credits、billing、错误 project、错误 key、Claude Code 使用量、provider 额度或状态事件，马上重试通常只是噪音。
买了 Claude Pro 或 Max 为什么 Claude Code 还会报错？
Claude Code 可能走订阅登录，也可能因为 ANTHROPIC_API_KEY 或环境配置走 API key 路线。先跑 /status，再查 active key 和模型上下文，不要直接把订阅当作 API 额度。
买更多 API credits 能修 Claude Code 限制吗？
不一定。只有当前入口确实是 API 资金或账单分支，credits 才有用。它不能修 Claude Code 订阅窗口、错误登录、provider quota、模型上下文压力或平台事件。
长上下文会造成这个错误吗？
会，但它只是一个分支。长上下文、1M context、模型族共享限制、输出过大和并发都可能造成 token 压力；必须结合 /status、model、token 量和小模型测试来判断。
provider 里报错但直接 Anthropic 没报错怎么办？
先看 provider dashboard 和 logs。provider 可能有独立 quota、project、billing、throttle 或模型映射。若 provider 传回上游 request id，把 provider id 和上游 id 都放进证据包。
支持工单里应该发什么？
发时间戳、时区、完整错误体、HTTP status、request id、当前入口、model、endpoint、安全的 org/project 标识、headers、Console/provider 状态、Claude Status 和近期变更。不要发 API key、bearer token、session token 或私密 prompt。
