Claude 使用限额已达上限怎么办？订阅与 API 429 处理方法

Claude 的使用限额是什么？

Claude 的使用限额分为两套系统，首先需要确定是哪一套限额阻止了您。Claude 订阅（Pro、Max、Team 或按席位计费的 Enterprise）提供滚动使用额度。该额度由不同模型共享，但部分模型系列有单独的上限，也与 Claude 聊天共享。因此，达到限额后会显示类似 You've hit your session limit · resets 3:45pm 的消息。按使用量计费的 Enterprise 计划目前是例外：这类计划不包含预付额度，从第一个 token 开始就按 API 费率计费。Claude API 衡量的是另一项指标：您每分钟发送请求和 token 的速度。达到限额后，它会返回类型为 rate_limit_error 的 HTTP 429 错误，以及一个 retry-after 标头，其中说明需要等待多少秒。

两类限额的处理方法完全不同。订阅限额取决于您在某个时间窗口内的使用量，因此您需要等待限额重置、购买更多使用量，或者使用计划提供的免费限额重置次数（如果有）。API 速率限额取决于您当前的请求速度。降低发送速度后，通常几秒内就会解除。

计划额度和速率限制层级编号经常变化，因此这里不提供具体数字；错误的数字不如不提供数字。请使用下文的命令查看您自己的限额。

触发了哪种限制？先阅读完整提示

Claude Code 会在输出的文本中说明具体系统。先确认提示中的系统与您的情况一致，再进行任何更改。

• You've hit your session limit · resets 3:45pm 表示订阅限制。您的套餐在当前时间窗口内的滚动额度已用完。
• You've hit your weekly limit · resets Mon 12:00am 表示同一系统的较长时间窗口限制。
• You've hit your Opus limit · resets 3:45pm 表示仅适用于 Opus 请求的订阅限制。切换到 Opus 系列之外的模型即可继续工作。
• You've hit your Sonnet limit · resets 3:45pm 表示同类模型系列限制，仅适用于 Sonnet 请求。切换到 Sonnet 系列之外的模型即可继续工作。
• 以 Fable limit reached 开头的提示表示您已用完每周额度中 Fable 模型可使用的部分。继续使用 Fable 会消耗用量积分，因此 Claude Code 会先要求您确认。使用 /model 选择其他模型，即可继续使用套餐额度。
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. 表示 API 速率限制。您触发了为 API key，或为 Amazon Bedrock 或 Google Cloud 项目配置的限制。具体取决于 客户端的身份验证方式；Bedrock 或 Vertex 客户端的用量计入云项目的配额，而不是 Anthropic 组织的配额。
• API Error: Server is temporarily limiting requests (not your usage limit) 表示与套餐配额无关的短暂限流。Claude Code 会先自动采用退避策略重试，之后才显示该提示。

订阅限制：会话、每周和 Opus 窗口

Pro、Max、Team 或按席位计费的 Enterprise 计划包含滚动使用额度。额度用尽后，Claude Code 会阻止后续请求，直到消息中显示的重置时间。该额度有两个特性最容易引起混淆。

• 该额度与 Claude 聊天共用。在 claude.ai 上进行的操作会消耗与终端操作相同的额度，因此，下午在聊天中大量使用会减少晚间编程可用的额度。使用同一账户登录的所有入口都会消耗同一额度池，因此在 Linux 上，测试版桌面应用和 Claude Code CLI 共用一个额度，而不是各自拥有一个额度。
• 该额度在不同模型之间共用。会话限制和每周限制适用于所有模型，共用同一个额度池。例外是该额度池中的模型系列上限：Opus 和 Sonnet 限制，以及 Max 和 Premium 席位提供的 Fable 额度，最高为每周限制的 50%。Pro 和 Standard 席位的计划限制完全不包含 Fable，首次请求起就会从使用积分中扣费。

对于 Claude for Teams 和按席位计费的 Enterprise，文档说明的额度形式是按席位提供的额度，按滚动五小时窗口和每周窗口重置，并与 Claude 聊天和 Cowork 共用；额度大小取决于席位层级（Standard 或 Premium）。当前按使用量计费的 Enterprise 计划则有所不同：没有可用尽的包含额度，使用量按 API 费率计费；上限取决于管理员为组织和单个用户设置的支出限制。在由销售协助的计划中，达到限制后停止的使用量会在下一个计费周期开始时恢复，除非提高该限制。对于 Pro 和 Max，消息中显示的重置时间以及您自己的 /usage 条是可靠数值，不要使用博客文章中的数据。若您仍在选择层级，Claude 计划选择指南会比较每种计划的限制范围。

使用 /model 切换模型为什么不会恢复会话或每周限额

这是最常见的错误操作。文档对此说明得很明确：所有模型共享会话限额和每周限额，因此切换模型不会恢复访问权限。会话窗口用尽后改用较小的模型，只会改变负责响应的模型。它不会改变剩余可用额度，因为会话额度和每周额度不是按模型分别计算的，切换模型没有可释放的额度。

例外是模型系列限额。如果消息显示 You've hit your Opus limit 或 You've hit your Sonnet limit，则 /model 是正确的解决方法。切换到该系列之外的模型即可继续工作，因为只有该系列的请求被阻止。Max 和 Premium 席位的 Fable 限额也是如此：切换到其他模型即可继续使用套餐额度，或者使用用量积分继续使用 Fable。不过，Fable 消耗共享每周池的速度高于其他模型，因此达到 Fable 限额后再切换，也无法突破整体每周限额。

将限额视为错误是第二个错误操作。重新安装或重新进行身份验证都不会改变任何情况。额度会在窗口重置时恢复，也可以通过消耗一次免费限额重置次数或购买用量积分恢复。

遇到订阅限额时的处理方法

1. 查看重置时间。会话窗口持续时间较短。每周窗口不适合一直坐在电脑前等待。在 Claude Code v2.1.234 或更高版本中，/rate-limit-options 可以等待重置，并自动继续执行中断的任务。
2. 如果达到 Opus、Sonnet 或 Fable 限额，请运行 /model，然后选择该系列之外的模型。
3. 运行 /usage 查看您的套餐限额、使用进度条以及重置时间。/cost 是进入同一界面的别名。
4. 在 claude.ai 或 Claude Desktop 中，打开 Settings > Usage，查看是否有 Resets 部分。符合条件的套餐有时会提供免费重置限额的选项。点击 "Reset for free" 后，您的五小时会话限额或每周限额会立即恢复为完整额度，具体取决于该优惠覆盖的限额。该按钮不会出现在终端或 IDE 中的 Claude Code，也不会出现在 Claude Mobile 中，并且每项优惠都有有效期。
5. 运行 /usage-credits，即可在达到限额后继续工作。对于 Pro 和 Max，该命令会打开账单设置。对于 Team 和 Enterprise，该命令会打开组织的使用情况设置；如果您没有账单访问权限，则会向管理员发送请求。
6. 如果您每周都会遇到相同的限制，说明当前套餐不适合您的工作方式。此时应评估突破使用限额的方法，而不是每次重置时才处理。

/usage-credits 需要通过 /login 登录 claude.ai 订阅。使用 API key 身份验证时无法使用该功能，因为 API key 没有关联可扩展的套餐额度。

使用量额度有一个需要提前了解的副作用。在订阅套餐中，提示缓存的有效期为一小时；开始使用额度后，有效期会缩短到五分钟。因此，更多轮次会从冷缓存开始，同样的工作会增加 Claude Code token 使用量。自行选择缓存 TTL 可以保持一小时的有效期。

看起来像使用量限制、但实际不是的消息

Claude Code 有 4 类错误会被报告为使用量限制，但它们都不是。

• 上下文或自动压缩警告不是使用量限制。当对话超过模型的上下文窗口后，/context 会先输出类似 Context exceeds the 200k-token limit by 94k tokens 的一行，然后输出用于释放空间的命令。压缩会总结较早的历史记录，以释放空间，但这并不是免费的：/compact 会读取它要总结的对话，因此压缩大型上下文本身也会消耗计划额度。需要重新开始而不是保留上下文时，/clear 不会产生费用。
• Prompt is too long · automatic compaction failed: <the underlying error> 表示自动压缩本身失败，具体原因由它报告。除非解决该错误，否则 /compact 会因同一错误持续失败。
• Credit balance is too low 表示您的 Console 组织已用完预付额度，或者 Claude Code 正通过 Console API key 发送订阅用户的请求；/status 会显示当前使用的凭据。在 platform.claude.com/settings/billing 添加额度，该页面也支持自动充值。
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context 是权限检查，不是配额耗尽。如果您选择了 Opus 4.6 或 Sonnet 4.6 的 [1m] 变体，请改用不带 [1m] 后缀的变体，或设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。如果该错误在对话中途出现，原因是上下文超过了 200K tokens，Claude Code 会自动将上下文压缩回标准限制以内。Sonnet 5 及更高版本、Opus 4.7 及更高版本、Haiku 5.5 和 Fable models 使用原生 1M 窗口，不需要移除后缀；该变量会将它们限制在 200K。

另一个错误来自 API。413 request_too_large 表示单个请求的大小限制，不是速率限制。

API 速率限制：429 实际统计的是什么

Messages API 会分别针对每个模型类别统计以下三项：

• 每分钟请求数（RPM）
• 每分钟输入 token 数（ITPM）
• 每分钟输出 token 数（OTPM）

您的组织还设有支出限制。这是另一项限制，表示 API 使用的每月最高费用。达到所在层级的支出上限后，API 使用会暂停，直到下个月开始，除非您申请提高限额。此时也会返回 429 rate_limit_error，但不会包含 retry-after 标头，并且 enforced_spend_limit_reached 位于 error.details.error_code 中。任何重试循环都无法解决此问题。

以下四项机制决定何时返回 429。

• 限制按模型类别分别计算。 限制分别应用于每个模型，因此您可以同时使用不同模型，直到分别达到各自的限制。部分模型系列共用同一个配额桶：Opus 速率限制是 Claude Opus 4.8、Opus 4.7、Opus 4.6 和 Opus 4.5 的总限制，而 Claude Sonnet 5 使用独立的限制。
• 容量会持续补充。 API 使用令牌桶算法，因此容量会持续恢复，而不是在固定时间重置。每分钟 60 个请求的限制可能按每秒 1 个请求执行，因此一次发出 60 个请求仍会失败。
• 对于大多数模型，只有未缓存的输入才会计入 ITPM。 input_tokens 和 cache_creation_input_tokens 会计入。对于大多数 Claude 模型，cache_read_input_tokens 不会计入；Claude Haiku 3.5 是文档中列出的例外。因此，缓存不仅可以降低费用，还可以增加速率限制余量。在输出方面，较高的 max_tokens 不会计入 OTPM，因为 OTPM 只统计实际生成的 token 数。
• 限制按组织级别计算。 您可以为工作区设置更低的限制，而组织级限制始终生效，即使各工作区限制的总和更高也是如此。工作区未单独设置的限制会继承组织限制，不会被视为无限制。

Start、Build、Scale 和 Custom 这些层级决定实际数值。系统会根据您的使用历史和账户状态自动分配层级。新组织以及使用历史较少的组织可能从 Evaluation 层级开始，其限制低于标准公开限制，因此首次收到 429 的时间可能早于表格预测。使用量突然增加会触发加速限制，即使您仍处于当前层级限制内，也可能返回 429，因此应逐步增加流量。所有公开数值都是上限：文档中的限制表示允许的最大使用量，不是保证的最低额度。如需提高限制，请在 Claude Console 的 Rate limits 页面使用 “Request tier increase”。

读取 429：retry-after、响应头和 SDK 重试

每个 API 错误都返回相同的封装结构：嵌套的 error 对象，其中包含类型和消息，以及顶层的 request_id。

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

其余信息位于响应头中。

• retry-after 表示重试请求前需要等待的秒数。提前重试会失败。
• anthropic-ratelimit-requests-limit、anthropic-ratelimit-requests-remaining 和 anthropic-ratelimit-requests-reset 描述您的请求配额。
• anthropic-ratelimit-input-tokens-* 和 anthropic-ratelimit-output-tokens-* 对 ITPM 和 OTPM 提供相同信息，后缀同样表示 limit、remaining 和 reset。
• anthropic-ratelimit-tokens-* 显示当前生效的限制中最严格的限制值。

重置时间响应头使用 RFC 3339 时间戳。剩余令牌响应头会舍入到最接近的千位，因此应将其作为概览指标读取。快速模式使用独立的配额池和独立的 anthropic-fast-* 响应头。请从任意一次成功调用中读取全部这些响应头：

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

每个响应还包含唯一的 request-id 响应头，例如 req_018EeWyXxfu5pfWkrYcMdjWG。在错误响应正文中，它显示为 request_id；在 Python 和 TypeScript SDK 响应中，它显示为 _request_id。联系支持团队时，请提供该值。

编写退避循环前，先确认是否确实需要。官方 SDK 会自动重试瞬时故障，包括连接错误、速率限制和 5xx 服务器错误。默认重试 2 次，并使用指数退避；存在 retry-after 响应头时，SDK 会遵循其指示。每个客户端都接受 maximum-retries 选项，可用于修改或禁用此行为。

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 overloaded_error 不是您的问题

429 表示请求发送过快。529 overloaded_error 表示 API 暂时过载，所有用户的流量较高时都可能出现此错误。这与您的密钥或代码无关。请使用指数退避策略重试。SDK 已针对 5xx 响应实现该策略。如果问题未消失，请查看 status.claude.com。500 api_error 表示内部错误，重试方式相同。这两种错误都不是速率限制。

读取自身限制，而不是查看表格

对于订阅，/usage 是需要关注的页面。它显示套餐用量条和消耗明细，d 或 w 可在最近 24 小时和最近 7 天之间切换。需要注意两点。Session 区块显示 API token 用量，面向 API 用户，因此订阅用户可以忽略其中的美元金额。这些数字来自该机器上的本地会话历史记录，因此其他设备或 claude.ai 产生的用量不会显示。

在 API 侧，Claude Console 中的 Usage 页面会显示两个图表：“Rate Limit - Input Tokens”和“Rate Limit - Output Tokens”。输入图表会将每分钟未缓存输入 token 的每小时最大值，与当前 ITPM 限制进行对比，并在旁边显示缓存率。这样可以监控用量是否接近限制，而不是等到生产环境中触发限制。

要以编程方式读取已配置的限制：

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

此操作需要 Admin API 凭据：Admin API key、具有 org:admin scope 的 OAuth token，或未限定到某个 workspace 的个人 key 或 service account key。Workspace API key 不可用。GET /v1/organizations/workspaces/{workspace_id}/rate_limits 可对每个 workspace 执行相同操作。两者均为只读操作；如需修改限制，请使用 Console 中的 Rate limits 页面。

减少用量，从而减少触及限制的次数

这两个系统底层统计的是同一项指标，因此这些调节方法都适用。

• 每轮使用更少的 token。 连续工作可保持缓存命中，在不相关任务之间执行 /clear 不会产生额外成本。Claude Code token 用量完整介绍了这些调节方法。
• 降低工作强度。 级别包括 low、medium、high、xhigh 和 max。/effort 菜单还提供 ultracode，但它会增加用量，而不是降低用量。机械式重命名无需深度推理。
• 收到 429 后降低并发。 降低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY，避免运行大量并行子代理。同时运行 /status：多余的 ANTHROPIC_API_KEY 可能会让请求改用低等级 key，而不是使用您的订阅。
• 将非交互式工作转移到 Message Batches API。 它会异步处理大量请求，输入和输出 token 均可享受 50% 折扣，并使用独立的速率限制，因此夜间任务不会与您的会话争用配额。

将大量数据注入上下文的任务最容易受到这些限制影响：如果您正在根据实时市场数据分析股票和期权，每个问题只提取所需的有限数据，其成本只是粘贴完整报价表和期权链的一小部分。由程序而非人员驱动的突发任务，应从一开始就使用 API key。迁移到 API 不仅会改变计量方式，也会改变付费方式，因为Claude API 没有免费层级。Max 和 Team 计划确实包含每月 API credits；关联 Console organization 后，您可以使用这些 credits 运行自己的应用和代理。这些 credits 不适用于 Claude Code，也不会改变您计划的用量限制。在 VPS 上运行您的第一个 Claude API 应用介绍了 key 管理和重试机制；如果让Claude Code 在 VPS 的 tmux 中运行，即使连接中断，长时间运行的代理任务也能继续执行。

FAQ

为什么切换模型无法解决 Claude 用量上限问题？

因为所有模型共享会话上限和每周上限。该额度属于套餐，而不是某个模型，因此 /model 只会改变用于回答的模型，不会改变剩余额度。例外是模型系列上限：You've hit your Opus limit 和 You've hit your Sonnet limit 仅适用于对应系列；Max 和 Premium 席位中的 Fable 上限也只限制 Fable。在这些情况下，切换模型才是文档规定的解决方法。

429 rate_limit_error 表示什么？我应该等待多久？

这表示您的账户触发了该模型类别的速率限制：每分钟请求数、每分钟输入令牌数或每分钟输出令牌数。响应会携带 retry-after 标头，其中包含需要等待的秒数；过早重试会失败。官方 SDK 已针对速率限制和 5xx 错误内置指数退避重试，默认重试 2 次，并遵循该标头。如果您仍在所属层级的限制范围内，却收到 429，通常表示突然提高请求速率触发了加速限制。如果 429 完全没有 retry-after 标头，则表示达到月度消费上限，等待几分钟无法解除该限制。

如何查看 Claude 用量上限以及重置时间？

在 Claude Code 中运行 /usage，查看套餐用量条、重置时间和用量明细；/cost 是其别名，d 或 w 可在最近 24 小时和最近 7 天之间切换。这些数据来自本地会话历史，因此不会包含其他设备和 claude.ai 的用量。对于 API，Console 会显示您的速率限制图表；使用 Admin API 凭据（例如 Admin API key）时，GET /v1/organizations/rate_limits 会返回已配置的限制。

达到 Claude 套餐上限后还能继续工作吗？

有时可以。在 Pro 和 Max 套餐中，运行 /usage-credits 可购买超出上限的用量；在 Team 和 Enterprise 套餐中，可使用它向管理员请求额外用量。该功能需要通过 /login 登录 claude.ai，使用 API key 进行身份验证时不可用。否则，请等待重置时间；如果 claude.ai 或 Claude Desktop 的 Settings > Usage 提供免费重置额度，也可以使用该额度；如果达到的是 Opus、Sonnet 或 Fable 上限，则切换模型；或者改用 API key，因为 API key 按每分钟计量，而不是按时间窗口计量。