Claude 使用限制达到后怎么办？订阅与 API 429 区别

Claude 的使用限制有哪些？

Claude 的使用限制分为两个独立系统。首先要确定是哪一个系统阻止了您的请求。Claude 订阅（Pro、Max、Team 或 Enterprise）提供滚动使用额度，该额度由不同模型和 Claude 聊天共享，因此达到限制时会显示类似 You've hit your session limit · resets 3:45pm 的消息。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 请求的订阅限制。这是唯一可以通过切换模型解决的情况。
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. 表示 API 速率限制。您触发了 API 密钥，或 Amazon Bedrock、Google Cloud 项目配置的限制。具体取决于 客户端的身份验证方式，因为 Bedrock 或 Vertex 客户端使用的是云项目的配额，而不是 Anthropic 组织的配额。
• API Error: Server is temporarily limiting requests (not your usage limit) 表示与套餐配额无关的短时限流。Claude Code 会先自动以退避策略重试，之后才显示这行提示。

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

订阅计划包含滚动使用额度。额度用尽后，Claude Code 会阻止后续请求，直到消息中显示的重置时间。该额度有两个特性最容易引起混淆。

• Claude chat 共享该额度。您在 claude.ai 上进行的操作与终端中的操作使用同一额度，因此在聊天中高强度使用一个下午，会缩短您晚上用于编码的可用时间。使用该账户登录的所有界面都共享同一额度，因此在 Linux 上，beta 桌面应用和 Claude Code CLI 共用一个额度，而不是各自拥有一个额度。
• 所有模型共享该额度。会话限额和每周限额不按模型分别分配，唯一的例外是 Opus 限额。

对于 Claude for Teams 和 Enterprise，文档所述的额度结构是：每个席位拥有一项额度，按滚动五小时窗口和每周窗口重置；该额度与 Claude chat 和 Cowork 共享，并根据席位层级（Standard 或 Premium）确定大小。对于 Pro 和 Max，以消息中显示的重置时间和您自己的 /usage 条为准，不要使用从博客文章中复制的数字。如果您仍在选择层级，您需要哪个 Claude 计划会比较每个计划的限制范围。

使用 /model 切换模型为何无法恢复访问

这是最常见的错误操作。文档对此有明确说明：会话限额和每周限额由所有模型共享，因此切换模型不会恢复访问权限。会话窗口内的额度用尽后，改用较小的模型，只会改变响应请求的模型。它不会改变剩余额度，因为额度从未按模型单独分配，所以切换模型也没有可释放的额度。

Opus 限额是例外，它确实是特定于模型的上限。如果消息显示 You've hit your Opus limit，正确的解决方法是 /model。切换到其他模型并继续工作，因为被阻止的只有 Opus 请求。

把限额问题当成故障是第二个错误操作。重新安装或重新进行身份验证都不会改变任何情况。额度会在窗口重置时恢复，或者在购买使用额度后恢复。

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

1. 查看重置时间。会话窗口很短。每周窗口不是坐在电脑前等一等就能过去的。
2. 如果达到 Opus 限额，请运行 /model 并选择其他模型。
3. 运行 /usage 查看套餐限额、用量条和重置时间。/cost 是打开同一界面的别名。
4. 运行 /usage-credits 以突破上限继续工作。在 Pro 和 Max 中，它会打开账单设置。在 Team 和 Enterprise 中，它会打开组织的用量设置；如果您没有账单访问权限，则会向管理员发送请求。
5. 如果您每周都会遇到同一个限制，说明当前套餐容量不适合您的工作方式。此时应一次性评估突破用量限额的途径，而不是每次重置时都重新处理。

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

使用用量额度前，您应先了解一个副作用。订阅状态下，提示缓存的有效期为 1 小时；开始使用额度后，有效期会缩短为 5 分钟。因此，更多轮次会从冷缓存开始，而完成相同工作所需的Claude Code token 用量会增加。

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

Claude Code 报告的以下 4 类错误会被误认为使用限制，但它们都不是。

• 上下文或自动压缩警告不是使用限制。当对话超过模型的上下文窗口后，/context 会输出类似 Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue. 的一行。系统会汇总较早的历史记录以释放空间，不会消耗您的套餐额度。
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. 表示 /compact 本身失败，因为剩余的可用上下文不足以容纳它要生成的摘要。
• Credit balance is too low 表示您的 Console 组织已用完预付额度。请在 platform.claude.com/settings/billing 添加额度；该页面也提供自动充值功能。
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context 是权益检查，不是配额耗尽。请选择不带 [1m] 后缀的模型变体，或设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。

API 还会产生另一类错误。413 request_too_large 表示单个请求超过大小限制，不是速率限制。

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

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

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

您的组织还设有支出限制。这是另一项限制，表示 API 使用的每月最高费用。达到所在层级的支出上限后，API 使用会暂停，直到下个月开始，除非您申请提高限额。重试循环无法解决此问题。

以下四项机制决定何时返回 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 这些层级决定实际数值。系统会根据您的使用历史和账户状态自动分配层级。新组织的初始限制可能低于标准公开限制，因此首次出现 429 的时间可能早于表格预测。使用量突然增加会触发加速限制，即使尚未达到所在层级的限制，也可能返回 429，因此应逐步提高流量。所有公开数值都是上限：文档中的限制表示允许的最大使用量，而不是保证的最低配额。如需提高限制，请在 Claude Console 的 Limits 页面中使用 "Request rate limit 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 令牌使用量，主要面向 API 用户，因此订阅用户可以忽略其中的美元金额。数据来自该设备上的本地会话历史，因此不会包含其他设备或 claude.ai 的使用量。

在 API 方面，Claude Console 中的 Usage 页面会显示两张图表：“速率限制 - 输入令牌”和“速率限制 - 输出令牌”。输入令牌图表将每分钟未缓存输入令牌数的每小时最大值，与当前 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 key，GET /v1/organizations/workspaces/{workspace_id}/rate_limits 可对每个工作区执行相同操作。两者都只读；如需修改限制，请使用 Console 中的 Limits 选项卡。

减少用量，避免更快触及限制

两套系统底层限制的是同一项资源，因此这些调整对两者都有效。

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

将大量数据写入上下文的任务对此最为敏感：如果您正在根据实时市场数据分析股票和期权，每个问题只提取所需的有限数据，成本只是粘贴完整报价表和期权链的一小部分。由程序而非用户驱动的突发任务，从一开始就应使用 API key。迁移后，计费方式和限流方式都会改变，因为Claude API 没有免费层级，注册时授予的小额额度除外。在 VPS 上运行您的第一个 Claude API 应用介绍了密钥管理和重试机制；如果让Claude Code 在 VPS 的 tmux 中运行，长时间运行的代理任务即使连接中断也能继续。

FAQ

切换模型为什么不能解决 Claude 使用限额问题？

因为所有模型共享会话限额和每周限额。配额属于套餐，而不是某个模型，因此 /model 只会改变回答所使用的模型，不会改变剩余配额。唯一的例外是 You've hit your Opus limit，它仅适用于 Opus 请求。在这种情况下，切换模型是官方文档建议的解决方法。

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

这表示您的账户触发了该模型类别的速率限制：每分钟请求数、每分钟输入 token 数，或每分钟输出 token 数。响应会通过 retry-after 标头返回需要等待的秒数，在此之前重试会失败。官方 SDK 已会使用指数退避自动重试速率限制错误和 5xx 错误，默认重试两次，并遵循该标头的值。如果您仍处于套餐层级限制以内却收到 429，通常表示突然增加请求量触发了加速限制。

如何查看 Claude 使用限额及重置时间？

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

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

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