# Claude Code Rate Limit Reached 怎么办：认出限额类型，原会话续跑

> Claude Code 报 Rate limit reached，先看提示原文：会话或每周限额等重置，模型家族限额换模型，429 查凭据；订阅登录可在原会话自动续跑。

- URL: https://blog.laozhang.ai/zh/posts/claude-code-rate-limit-reached
- Published: 2026-02-04
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, Rate Limit, Anthropic, AI Coding, Troubleshooting

---
Claude Code 干到一半停下，屏幕上出现 `API Error: Rate limit reached` 或类似的一行时，先别重发、别重装。截至 2026 年 10 月 5 日，Claude Code 的[错误参考页](https://code.claude.com/docs/en/errors)已经把"限额"拆成好几条更具体的提示：订阅的会话额度、每周额度、Opus 或 Sonnet 模型家族额度、服务端临时限流、API key 或云厂商项目的 429、1M 上下文权限、用量积分的消费上限。它们的处理办法各不相同，有的等重置，有的换个模型就能接着干，有的只是凭据走错了。你看到报错时，能自动重试的情况 Claude Code 已经重试过了；订阅登录的交互会话还会在原地等额度重置后自动接着做原来的任务。

## 先对照提示原文：Rate limit reached 现在多半是下面哪一句

把终端里那一行完整看一遍（往上翻也行），对照下表。表里的 `3:45pm`、`Mon 12:00am` 只是示例时间，你的提示会写实际的重置时间。

| 你看到的提示 | 是什么限制 | 换模型有没有用 | 下一步 |
| --- | --- | --- | --- |
| `You've hit your session limit · resets 3:45pm` | 订阅的会话额度，Pro 和 Max 每 5 小时重置一次 | 没用，所有模型共用 | 等提示里的重置时间；订阅登录的交互会话会自动续跑 |
| `You've hit your weekly limit · resets Mon 12:00am` | 订阅的每周额度，跨所有模型 | 没用 | 重置可能在几天后，自动续跑不会替你等这么久；需要马上继续就用 `/usage-credits` |
| `You've hit your Opus limit` 或 `You've hit your Sonnet limit` | 单个模型家族的额度 | 有用 | `/model` 换到另一个家族就能接着干 |
| `Usage limit reached · limit resets 3:45pm`，下一行 `Continuing automatically at 3:45pm` | 不是新错误，是自动续跑正在等重置 | 等待期间用 `/model` 换模型，Claude Code 会检查能否立刻继续 | 保持会话开着；按 Esc 取消等待 |
| `API Error: Server is temporarily limiting requests (not your usage limit)` | 服务端的短时限流，跟你的套餐额度无关 | 不相关 | 稍等再试；持续出现就看 [status.claude.com](https://status.claude.com) |
| `API Error: Request rejected (429) · this may be a temporary capacity issue...` | 你的 API key、Amazon Bedrock 项目或 Google Cloud 项目配置的限流 | 换更小的模型可以降低压力 | `/status` 确认当前凭据，再看云厂商控制台 |
| `API Error: Usage credits required for 1M context · ...` | 1M 上下文的使用权限检查，不是额度用完 | 有用：换成不带 `[1m]` 的版本 | `/model` 选标准上下文版本 |
| `You've hit your monthly spend limit · ...` 及 individual、org、team 等变体 | 用量积分到了消费上限 | 没用 | 提高上限，或等提示里写的窗口重置时间 |
| `spend limit reached (daily; resets ...)` | Claude apps gateway 运营方设的消费上限 | 没用 | 等重置，或找网关管理员 |

几条判断口径来自错误参考页本身：会话和每周额度在所有模型之间共享，所以换模型不会恢复；Opus 和 Sonnet 额度只管自己那个家族；服务端临时限流和你的套餐配额无关，Claude Code 靠响应里有没有配额信息来区分两者；1M 上下文那条在会话和每周额度都还有剩余时也会触发。消费上限类提示不会自动重试，等也只能等到它写明的重置时间。

如果终端报的是 529 过载或 500，那不是限额问题，分别看 [Claude Code 报 529 过载怎么办：换模型还是等待](https://blog.laozhang.ai/zh/posts/claude-code-overloaded-error) 和 [Claude Code API Error 500 怎么办：恢复原会话，不重做已完成操作](https://blog.laozhang.ai/zh/posts/claude-code-500-529-rate-limit)。同一句提示在 Claude.ai 网页、Claude Code 和 API 之间该归谁管，[Claude Rate Exceeded 错误：先确认限制归属再重试](https://blog.laozhang.ai/zh/posts/claude-rate-exceeded-error) 有跨入口的判断。

![Claude Code 按提示原文选择下一步：共享额度、模型家族、服务端限流、API 429、1M 权限与消费上限](https://blog.laozhang.ai/posts/zh/claude-code-rate-limit-reached/img/diagnostic-flowchart.webp)

## 只看到 "API Error: Rate limit reached" 这一句：用四个命令判断

这句原话并没有消失。Claude Code 的 hooks 文档在 `StopFailure` 事件的示例里，仍然用 `"error": "rate_limit"`、`"error_details": "429 Too Many Requests"`、`"last_assistant_message": "API Error: Rate limit reached"` 来演示一次因限额结束的回合。只是错误参考页没有为这句话单列条目，哪些版本、哪些登录方式还会只显示这一句，也没有公开说明。所以只看到这一句时，用下面四个命令把它归到上表的某一行：

```bash
/usage
/status
/model
claude --version
```

- `/usage`（`/cost`、`/stats` 是它的别名）显示套餐额度、各窗口用了多少、什么时候重置。接近或达到 100%，按上表的会话、每周或模型家族那几行处理。
- `/status` 看的是账号、当前凭据、模型和连接状态，不是剩余额度。重点看登录方式是不是你的订阅，有没有一个 `API key` 行在生效。
- `/model` 看当前模型名后面有没有 `[1m]`。
- `claude --version` 记下版本号。错误参考页多处注明提示从哪个版本开始改变：比如 v2.1.199 之前，订阅登录遇到服务端临时限流会直接失败而不是自动重试；1M 上下文那条提示在 v2.1.268 改过措辞。版本越旧，你看到的提示越可能和上表对不上。

如果 `/usage` 显示额度还很充沛，`/status` 也确认是订阅登录，直接跳到下面"用量还很充沛"那一节。

## 被限额打断后，在原会话里接着干

额度类限制最容易犯的错，是关掉会话、重开一个、再把需求贴一遍。Claude Code 本身已经做了大部分恢复工作，你要做的主要是别打乱它。

### 不要连续重发：报错出现前已经重试过

Claude Code 对临时性失败会先按指数退避自动重试，默认最多 10 次（`CLAUDE_CODE_MAX_RETRIES`），等待时转圈处显示 `Retrying in Ns · attempt x/y`。临时性的 429 限流也在重试范围内，订阅登录从 v2.1.199 起同样如此。所以当报错真正显示出来，适用的重试已经做完了，手动连发同一条消息很少有用。

如果中断发生在 Claude 已经写完一段文字或完成一次工具调用之后，Claude Code 不会整轮重跑，以免同一个工具调用执行两遍；它保留已完成的部分，并提示 `The response above may be incomplete`。这时看看屏幕上留下了什么，回复 `continue` 让它从最后完成的地方接着做。

子代理也一样：前台子代理被限额打断时如果已经产出文字，主对话拿到的是标了"未完成"的部分结果；如果显示 `Agent terminated early due to an API error:` 加一段详情，按冒号后的详情对照上表处理，限制解除后让 Claude 重试那项任务或恢复那个子代理。

### 等额度重置：自动续跑和 /rate-limit-options

从 v2.1.234 起，用 claude.ai 订阅登录的交互会话撞到用量限额时，Claude Code 会在原会话里等待，额度重置后自动接着做被打断的任务。这个功能默认开启，底部会显示：

```text
Usage limit reached · limit resets 3:45pm
Continuing automatically at 3:45pm · esc to cancel
```

几点要知道：

- **它不会重发你的上一条消息**，而是让 Claude 从停下的地方继续。续跑时权限确认照常弹出，你不在电脑前时任务可能停在某个确认上。
- **会话要开着**。退出 Claude Code 后再恢复会话，等待不会重新开始；用 `/login` 换账号、清空或回退对话、`/resume` 到别的会话，也会结束等待。
- 续跑后又撞限额，它最多自动重新等待两次，之后停下并提示 `Automatic continue stopped after repeated usage-limit hits · /rate-limit-options to try again`。
- 每周额度这类重置时间在 24 小时以后的，以及你正在用其他家族模型时出现的 Opus 或 Sonnet 限额，它不会自动开始等待。

不想等，或者自动续跑没启动时，运行 `/rate-limit-options`：菜单里有"等待并自动继续"、加用量积分、升级套餐几项。按 Esc 或在菜单里选"Don't continue automatically"可以取消等待。想彻底关掉，在 `/config` 里关闭"Continue automatically at usage limit"，或在用户设置里写 `autoContinueAtUsageLimit: false`。桌面版 Code 标签页的会话额度卡片有单独的"Auto-continue when limits reset"复选框，与 CLI 的设置互不影响。

后台会话、`-p` 非交互运行、API key 和云厂商计费不提供这种等待：按请求计费的路径本来就没有可等的重置时间。

### 不想等：换模型家族或加用量积分

- **Opus 或 Sonnet 限额**：`/model` 换到另一个家族就能继续。代价是每个模型有自己的提示缓存，换过去后的下一次请求要把整段对话重新读一遍，没有缓存命中，消耗比平时多。
- **会话或每周限额**：换模型没用。Pro 和 Max 可以用 `/usage-credits` 购买用量积分，按标准 API 价格继续；Team 和 Enterprise 成员用这个命令向管理员申请。等待期间用 `/usage-credits` 加完积分，Claude Code 会检查额度并立刻继续；绕开它、自己在浏览器里购买或升级，则不会触发这个检查，要等重置或手动发消息。用量积分怎么计费、和限额重置有什么区别，见 [Claude 额外使用费用：用量积分、Max 和 Claude Code 账单怎么判断](https://blog.laozhang.ai/zh/posts/claude-extra-usage-cost) 与 [Claude 云端会话赠金、用量积分和限额重置：区别与使用顺序](https://blog.laozhang.ai/zh/posts/claude-cloud-session-credit-vs-usage-credits)。

### 无人值守的会话：CI、后台和远程控制

CI 这类没人盯着的运行可以设 `CLAUDE_CODE_RETRY_WATCHDOG=1`，让 429 和 529 容量错误无限重试，而不是重试完默认次数就失败；但遇到报告消费上限或用量积分耗尽的 429，它会立刻失败，不会空等。在远程控制、后台会话或 agent team 的队友会话里，如果看到 `Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent`，要处理的是一个确认框：询问是否动用用量积分的提示没人回答，请求根本没发出去。回到会话运行的终端再发一条消息，在确认框重新出现时回答它，或用 `/model` 换一个不走用量积分的模型。

## API key、Bedrock、Vertex 报 429：先确认当前用的是哪个凭据

`API Error: Request rejected (429)` 说明撞到的是你的 API key、Amazon Bedrock 项目或 Google Cloud 项目配置的限流。提示末尾那句会写去哪里查服务状态，用了自定义 `ANTHROPIC_BASE_URL` 时写的是网关地址；代理或网关自己返回 HTML 错误页时，`·` 后面是那个页面的标题，比如 `Too Many Requests`。

先运行 `/status` 看当前生效的凭据。环境里残留的 `ANTHROPIC_API_KEY` 会让 Claude Code 走 API 计费，而不是你的订阅，请求可能就落在一个额度很低的 key 上。你本来想用订阅时，把这个变量从当前终端和 shell 配置文件里删掉，重开 `claude`，必要时 `/login`。两种计费方式的区别见 [Claude Code API Key 和订阅计费怎么选：先看 /status](https://blog.laozhang.ai/zh/posts/claude-code-api-key-vs-subscription-billing)。

确实要走 API key 或云厂商时，去对应控制台看当前生效的限额，需要时申请提高；同时降低并发：调低 `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`，少开并行子代理，大批量脚本任务用 `/model` 换小一点的模型。API 各档位的限额和提额方式，见 [Claude Rate Exceeded 错误：先确认限制归属再重试](https://blog.laozhang.ai/zh/posts/claude-rate-exceeded-error)。

## 用量明明还很充沛却报限额：1M 上下文、凭据和账号侧问题

`/usage` 显示额度还剩很多、每条请求却都被拒，按下面的顺序排查，重装和加钱放在最后。

**1M 上下文版本。** `Usage credits required for 1M context` 是权限检查，不是额度用完，会话和每周额度还有剩余时照样会出现。截至 2026 年 10 月 5 日，它只涉及 Opus 4.6 和 Sonnet 4.6 的 `[1m]` 版本：Max、Team、Enterprise 套餐里 Opus 4.6 的 1M 包含在订阅内，Sonnet 4.6 的 1M 需要用量积分；Pro 两者都需要用量积分。Fable 5.1、Fable 5、Sonnet 5 及以后、Opus 4.7 及以后的模型在所有套餐（包括 Pro）都默认 1M 上下文，没有 `[1m]` 版本可选，也不需要为此开用量积分。处理办法：

- `/model` 选不带 `[1m]` 的版本，回到标准上下文。
- 换了还报，说明别处的配置里写了 1M 模型 ID，按[模型配置文档](https://code.claude.com/docs/en/model-config)列出的优先级逐个检查。
- 不想再看到 1M 版本，设 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。
- 对话中途因为超过 200K Token 触发这条提示时，Claude Code 会自动压缩回标准上限，不用你处理；v2.1.172 之前的版本会每条请求都报，连 `/compact` 也失败，那就用 `/clear`。

GitHub 上 2026 年 2 月底开的 [#29579](https://github.com/anthropics/claude-code/issues/29579)（Max 订阅、用量 16%、每条请求都报 `API Error: Rate limit reached`）下，有用户发现自己用的是 `opus[1m]`，`/model` 里写着按额外用量计费；也有几位换模型后恢复。这些是个人报告，官方没有给出统一原因，但足以说明：报错前先看一眼模型名。

**凭据走错。** 上一节的 `ANTHROPIC_API_KEY` 残留同样会让"订阅明明有额度"的人撞上 API key 的限流。`/status` 一看便知。

**安装和版本。** 在 shell 里运行 `claude doctor` 做只读诊断，或在会话内运行 `/doctor`，后者会检查重复或残留的安装、`PATH` 问题和无法解析的设置文件。旧安装挡在新安装前面时，你以为在用新版，实际跑的是旧版。

**账号侧问题。** 有用户报告只有某个入口出错：[#33120](https://github.com/anthropics/claude-code/issues/33120) 里，同一账号的 Cowork 每个操作都报 `API Error: Rate limit reached`，Claude 网页聊天和 Claude Code CLI 却正常，换另一个账号的 Cowork 也正常。报告者换一台电脑也复现，这种情况重装本地软件没有用，应该带着证据上报。还要记得 Pro 和 Max 的额度在 Claude 网页、Claude Code、桌面版和 IDE 之间共用，别处的使用也算在里面。

## 带证据上报：/feedback 之前先记下这几项

确认不是上面任何一种情况后，再上报。先把这些记下来，支持人员和 issue 里的其他人才能对上号：

- 提示的完整原文和出现时间（带时区）
- `claude --version` 的输出
- `/status` 里的登录方式、凭据和当前模型（包括是否带 `[1m]`）
- `/usage` 里各窗口的百分比和重置时间
- 换模型、换账号、换入口（网页、桌面版、Cowork）后是否复现
- 当时 [status.claude.com](https://status.claude.com) 有没有进行中的事故

然后在 Claude Code 里运行 `/feedback`，它会把会话记录和你的描述发给 Anthropic，也可以生成一个预填好的 GitHub issue；用 Bedrock、Vertex 等第三方服务时，它会在本地保存一个归档，交给你的 Anthropic 客户代表。发 issue 之前先搜一下 [anthropics/claude-code 的现有 issue](https://github.com/anthropics/claude-code/issues)，有同样症状就补充到那里。

团队想统计这类中断，可以配置 `StopFailure` hook，用 `rate_limit` 作为匹配条件记录日志或发通知。这类 hook 只能记录和提醒，不能改变 Claude Code 的处理方式。

## 下次少撞限额：清上下文、选模型、少开并行

Claude Code 和网页聊天不一样：它会读文件、搜索、跑命令、跑测试，再把这些输出带回模型。你看到的一条命令背后可能是多次请求，而且对话越长、读进来的文件和日志越多，后面每一次请求都越重。会话额度和每周额度是同时计算的，一次大规模并行任务甚至可能在会话窗口重置之前就把每周额度用完。

![Claude Code 请求由短指令、系统提示、对话历史、相关文件和工具输出共同组成，并在后续工具调用中累积上下文的概念示意](https://blog.laozhang.ai/posts/zh/claude-code-rate-limit-reached/img/token-consumption.webp)

日常最有效的几件事：

- 换任务就 `/clear`；同一任务对话太长时用 `/compact`，后面加上要保留的重点。
- 大部分编码用 Sonnet，把 Opus 留给多文件重构和架构决策；降低推理强度也能省。
- 关掉用不到的 MCP 服务器；子代理同样消耗额度，不要无节制并行。
- 让 Claude 只看相关目录，测试失败时贴关键报错，不要整份日志丢进去。
- 想提前知道快用完了：额度用到一定比例时 Claude Code 会提示，比如 `You've used 85% of your session limit · resets 3:45pm`；也可以把 `rate_limits` 字段加进自定义状态栏，持续显示剩余额度。

怎么按 5 小时和每周窗口安排工作、怎么查清楚额度花在了哪里，见 [Claude Code 用量查看与 Token 审计：5 小时和每周额度、缓存与 MCP](https://blog.laozhang.ai/zh/posts/claude-code-usage-limit-issues)。

## 关于 Claude Code 限速恢复和升级的问题

**Claude Code 限速多久恢复？**

看提示本身。会话、每周、模型家族限额的提示里都写着重置时间，`/usage` 也能看到；Pro 和 Max 的会话额度每 5 小时重置，每周额度在账号固定的时间重置，官方没有公布具体的小时数或消息条数。服务端临时限流通常很快就过去。API key 和云厂商的 429 没有统一的重置时间，以控制台显示为准。

**Claude 不够用，要不要升级 Max？**

先排除不是额度的情况：1M 上下文提示、凭据走错、模型家族限额（换模型就能继续）。排除之后，如果你经常在任务中途被会话或每周额度卡住、而等待的成本高于升级差价，再考虑升级；只是偶尔不够，用量积分按需补更灵活。两档套餐的比较见 [Claude Pro vs Max 怎么选（2026）：价格、Claude Code 限制与 Max 是否值得](https://blog.laozhang.ai/zh/posts/claude-code-pro-vs-max)。

**"Api rate limit reached please try again later" 怎么解决？**

如果它出现在 Claude Code 里，而你用的是 API key、Bedrock 或 Vertex，按上面 429 那一节处理：确认凭据、看控制台限额、降低并发。如果它来自别的工具或中转服务，那是那个服务自己的限流，要看它的文档和控制台，Claude 的 `/usage` 显示不了它的状态。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-05。

- [错误参考页](https://code.claude.com/docs/en/errors) (code.claude.com)
- [status.claude.com](https://status.claude.com/) (status.claude.com)
- [模型配置文档](https://code.claude.com/docs/en/model-config) (code.claude.com)
- [#29579](https://github.com/anthropics/claude-code/issues/29579) (github.com)
- [#33120](https://github.com/anthropics/claude-code/issues/33120) (github.com)
- [anthropics/claude-code 的现有 issue](https://github.com/anthropics/claude-code/issues) (github.com)