Claude 使用限额触发了怎么办

Claude 的使用限额是什么？

Claude 的使用限额来自两套独立的系统，第一步是先判断是哪一套把你拦住了。Claude 订阅（Pro、Max、Team 或 Enterprise）提供一种滚动式的使用额度，在不同模型之间共享，也与 Claude 聊天共享，因此它会用类似 You've hit your session limit · resets 3:45pm 的消息来阻止你。Claude API 衡量的是另一回事：你的请求和令牌发送速度，按每分钟计数。它会用 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 项目所配置的限额。
• API Error: Server is temporarily limiting requests (not your usage limit) 是与套餐配额无关的短期限流。Claude Code 会在向你显示该提示之前，按退避策略自动重试。

订阅额度:会话、每周与 Opus 窗口

订阅计划包含一个滚动用量配额。当配额用尽时,Claude Code 会阻止后续请求,直到消息中显示的重置时间。该配额有两个特性是大部分困惑的来源。

• 它与 Claude 聊天共享。你在 claude.ai 上完成的工作和终端里的工作共用同一份配额,因此在聊天中度过的一个繁忙下午会缩短你晚上写代码的时间。
• 它跨模型共享。会话和每周限额不区分模型,唯一的例外是 Opus 限额。

在 Claude for Teams 和 Enterprise 上,文档描述的形式是按席位计算的配额,按滚动五小时窗口和每周窗口重置,与 Claude 聊天和 Cowork 共享,并按席位等级(Standard 或 Premium)确定大小。在 Pro 和 Max 上,消息中打印的重置时间和你自己的 /usage 进度条是可靠的数据,而非从博客文章中复制的数字。如果你还在选择等级,选择哪个 Claude 套餐对比了各套餐所限制的内容。

为什么用 /model 切换模型无法恢复访问

这是最常见的错误操作，文档对此直言不讳：会话和每周限额在所有模型之间共享，因此切换模型并不能恢复访问。在会话窗口用尽后选择较小的模型，只会改变回答你的模型。它不会改变剩余的额度，因为额度从来不是按模型单独持有的，所以切换模型并没有释放任何东西。

唯一的例外是 Opus 限额，它是一个真正针对特定模型的上限。如果提示信息是 You've hit your Opus limit，那么正确的解决办法是 /model。请切换到其他模型继续工作，因为只有 Opus 请求被拦截了。

把限额当作 bug 是第二种错误做法。重新安装或重新认证都不会改变任何东西。额度会在窗口重置时恢复，或者在你购买使用额度后恢复。

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

1. 查看重置时间。会话窗口很短。周窗口不适合坐在桌前干等。
2. 如果是 Opus 限额，运行 /model 并选择其他模型。
3. 运行 /usage 查看套餐限额、进度条以及重置时间。/cost 是同一界面的别名。
4. 运行 /usage-credits 可在达到上限后继续工作。在 Pro 和 Max 上，它会打开账单设置。在 Team 和 Enterprise 上，它会打开组织的用量设置；如果你没有账单权限，则会向管理员发送请求。
5. 如果每周都撞上同一道墙，说明套餐规模与你的工作方式不匹配。

/usage-credits 需要通过 /login 登录的 claude.ai 订阅。它不支持 API 密钥认证，因为 API 密钥没有可扩展的套餐额度。

使用额度有一个值得先了解的副作用。订阅状态下，提示缓存生命周期为一小时；一旦开始消耗额度，缓存生命周期会降至五分钟，因此更多轮次会以冷启动开始，Claude Code 令牌用量 在相同工作量下会上升。

那些看起来像用量上限但其实不是的错误

在 Claude Code 中,有四种错误常被误报为用量上限,实际上都不是。

• 上下文或自动压缩警告不是用量上限。当对话长度超出模型的上下文窗口后,/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 计入。cache_read_input_tokens 在大多数 Claude 模型上不计入，已记录的例外是 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-* 显示当前生效的最严格限制的对应值。

reset 响应头是 RFC 3339 时间戳。剩余 token 的响应头会被四舍五入到最近的千位，因此只能将其作为大致参考。Fast 模式拥有独立的配额池和独立的 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 服务器错误，默认采用指数退避重试两次，并在存在 retry-after 响应头时遵循其值。每个客户端都提供 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 暂时过载，当 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 key,GET /v1/organizations/workspaces/{workspace_id}/rate_limits 在每个工作区上执行同样的操作。两者都是只读的:要修改限额,请使用 Console 中的 Limits 选项卡。

减少用量,从而避开更多限制

两套系统在底层计量的是同一件事,因此这些调节手段在两者上都有效。

• 降低单轮 token 消耗。 持续的任务会话可以让缓存保持温热,在不相关的任务之间使用 /clear 不会带来额外开销。Claude Code 的 token 用量 对这些手段做了完整介绍。
• 降低推理强度。 等级依次为 low、medium、high、xhigh 和 max。/effort 菜单还提供 ultracode,该选项会增加消耗,而不是降低消耗。在一个机械的重命名任务上开启深度推理毫无意义。
• 在收到 429 后降低并发。 调低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY,并避免大量并行子代理。同时运行 /status:一旦出现零散的 ANTHROPIC_API_KEY,请求就会经由一个低档密钥路由,而非你的订阅。
• 将非交互式任务迁移到 Message Batches API。 它以异步方式大批量运行,输入和输出 token 均享受 50% 折扣,并使用独立的速率限制,因此夜间任务不再与你的会话争抢配额。

由程序而非人工驱动的突发性工作,从一开始就应该走 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 密钥调用 GET /v1/organizations/rate_limits 会返回你配置的限额。

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

取决于情况。运行 /usage-credits 可以在 Pro 和 Max 上购买超额用量,或在 Team 和 Enterprise 上向管理员申请;该命令需要通过 /login 登录 claude.ai,使用 API 密钥认证时不可用。否则只能等待重置时间,如果是 Opus 上限则切换模型,或者改用 API 密钥,它按分钟计费,而不是按窗口计费。