claude-sonnet-5.5 报 HTTP 429 怎么办?请求数和 Token 配额如何分开排查
11 月 11 日晚上,我给代码任务开了 6 个 worker。并发不算高,日志却连续刷 429。降到 3 个还是报。折腾半天才发现,请求数没超,是几份超长 diff 把输入 Token 配额顶满了。
claude-sonnet-5.5 出现 HTTP 429 时,别急着只降并发。先读取 retry-after,结合响应头和本地统计,分别检查每分钟请求数、输入 Token 数和输出 Token 数。响应里没有 retry-after,就用带随机抖动的指数退避,免得多个 worker 按固定间隔一起重试。
截至 2026 年 11 月 14 日,Anthropic 官方文档把 429 定义为 rate_limit_error。具体限额取决于账户的使用层级,没有一套适用于所有账户的固定 RPM 或 TPM 数字。
为什么会出现这个问题
我当时看到的完整报错是:
HTTP 429 rate_limit_error: Your account has hit a rate limit.
这个错误不代表服务挂了。Anthropic 对这几类状态的定义如下:
| 状态 | 含义 | 应用侧动作 |
|---|---|---|
| HTTP 429 | 触及速率限制 | 限流、排队、延迟重试 |
| HTTP 500 | 服务端内部异常 | 有上限地重试并记录请求 |
| HTTP 529 | 服务暂时过载 | 延迟重试,必要时降级 |
真正麻烦的是,速率限制往往不止一项。
| 限额维度 | 常见触发场景 | 本地可观察指标 |
|---|---|---|
| 每分钟请求数(RPM) | worker 数量多、短请求密集、失败后立即重试 | 60 秒滑动窗口内的请求数量 |
| 每分钟输入 Token 数(ITPM) | 长上下文、超长 diff、重复发送历史消息 | 每次请求估算的输入 Token |
| 每分钟输出 Token 数(OTPM) | max_tokens 较大、多个长回答同时生成 | 实际输出 Token 与预留额度 |
| 并发中的未完成请求 | 单次响应慢、流式连接持续时间长 | in-flight 请求数和请求耗时 |
所以,把并发从 6 降到 3 只能减少请求数量和在途请求,不能保证输入 Token 配额立刻恢复。假设三个 worker 同时提交各 150,000 Token 的上下文,总输入量仍可能高于账户当前窗口允许的额度。
先确认 429 来自哪里
先保留响应状态、错误体和关键响应头,不要只记录一句“调用失败”。
def log_rate_limit_response(response):
keys = [
"retry-after",
"anthropic-ratelimit-requests-limit",
"anthropic-ratelimit-requests-remaining",
"anthropic-ratelimit-requests-reset",
"anthropic-ratelimit-input-tokens-limit",
"anthropic-ratelimit-input-tokens-remaining",
"anthropic-ratelimit-input-tokens-reset",
"anthropic-ratelimit-output-tokens-limit",
"anthropic-ratelimit-output-tokens-remaining",
"anthropic-ratelimit-output-tokens-reset",
]
print("status:", response.status_code)
print("body:", response.text[:2000])
for key in keys:
value = response.headers.get(key)
if value is not None:
print(f"{key}: {value}")
不同 SDK、API 版本和中转层暴露的响应头可能不同,因此代码要允许字段缺失。至少需要记录:
timestamp
request_id
model
status_code
retry_after
input_tokens_estimated
input_tokens_actual
output_tokens_actual
worker_id
attempt
latency_ms
如果错误体来自自己的 Nginx、API Gateway 或任务队列,而不是模型服务端,排查方向也不同。例如下面两条日志虽然都是 429,来源并不一样:
nginx: 429 limiting requests, excess: 2.410 by zone "api_limit"
anthropic: 429 rate_limit_error: Your account has hit a rate limit.
方案介绍:把请求数和 Token 分开控制
建议在发送请求前设置两层限制:
- 请求桶控制 RPM,避免短时间内发出过多请求。
- Token 桶控制输入量,长上下文需要消耗更多配额。
- 额外设置
max_in_flight,防止慢请求把连接池占满。 - 收到 429 后优先服从
retry-after,否则执行指数退避。
request_bucket.consume(1)
input_token_bucket.consume(estimated_input_tokens)
semaphore.acquire()
try:
call_model()
finally:
semaphore.release()
如果调用链需要经过聚合网关/中转,OpenRouter 或 ofox.io 可以作为候选方案之一;无论使用哪种路径,都应把 status_code、retry-after、上游错误体和实际 usage 写入日志,否则很难判断 429 来自本地网关、平台账户还是模型提供方。
Token 估算不必追求完全精确,但要留出误差。比如按估算值额外预留 10%:
reserved_input_tokens = int(estimated_input_tokens * 1.10)
如果请求包含工具定义、系统提示词、历史消息或附件解析结果,这些内容也要计入输入。只统计用户最后一条消息,通常会明显低估。
如何判断是 RPM 还是 Token 配额
最直接的方法是同时维护两个 60 秒滑动窗口。
from collections import deque
from time import monotonic
request_events = deque()
token_events = deque()
def trim(events, now, window=60):
while events and now - events[0][0] >= window:
events.popleft()
def current_usage():
now = monotonic()
trim(request_events, now)
trim(token_events, now)
rpm = len(request_events)
input_tpm = sum(tokens for _, tokens in token_events)
return rpm, input_tpm
def record_request(input_tokens):
now = monotonic()
request_events.append((now, 1))
token_events.append((now, input_tokens))
观察结果通常有三种:
RPM 接近上限,TPM 较低 -> 减少请求频率或合并小请求
RPM 较低,TPM 接近上限 -> 缩短上下文、切分长任务或延后发送
RPM 和 TPM 都接近上限 -> 同时排队,并分别等待两个桶释放容量
不要仅根据 worker 数量推断 RPM。一个 worker 如果失败后立即循环重试,也可能在一分钟内制造大量请求。
配置示例
下面是一份按请求、输入 Token 和并发数分别限流的配置:
model:
name: claude-sonnet-5.5
timeout_seconds: 120
max_output_tokens: 4096
rate_limit:
requests_per_minute: 40
input_tokens_per_minute: 240000
output_tokens_per_minute: 80000
max_in_flight: 3
token_estimate_margin: 1.10
retry:
max_attempts: 5
base_delay_seconds: 1
max_delay_seconds: 60
jitter: full
honor_retry_after: true
logging:
record_response_headers: true
record_usage: true
record_request_id: true
当 base_url 配置为 OpenRouter 或 ofox.io 这类聚合网关/中转地址时,仍应保留客户端侧的 requests_per_minute、input_tokens_per_minute 和 max_in_flight;同时确认鉴权头、模型名称及错误体格式,因为中转返回的 429 字段不一定与 Anthropic 直连完全一致。
provider:
base_url: "${MODEL_BASE_URL}"
api_key: "${MODEL_API_KEY}"
model: "claude-sonnet-5.5"
forward_headers:
- request-id
- retry-after
加载配置后,可以在发送前同时申请请求额度和 Token 额度:
async def send_with_limits(client, payload, limiter):
estimated = estimate_tokens(payload)
reserved = int(estimated * limiter.token_estimate_margin)
await limiter.request_bucket.acquire(1)
await limiter.input_token_bucket.acquire(reserved)
async with limiter.in_flight:
return await client.messages.create(**payload)
如果实际输入 Token 少于预留值,可以在拿到 usage 后返还差额;如果无法返还,也可以仅用实际值修正后续估算,避免调度器越来越保守。
正确处理 retry-after
retry-after 可能是秒数,也可能是日期。客户端应兼容两种形式,并设置最大等待时间。
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
def parse_retry_after(value, now=None):
if not value:
return None
try:
return max(0.0, float(value))
except ValueError:
pass
now = now or datetime.now(timezone.utc)
try:
target = parsedate_to_datetime(value)
if target.tzinfo is None:
target = target.replace(tzinfo=timezone.utc)
return max(0.0, (target - now).total_seconds())
except (TypeError, ValueError, OverflowError):
return None
有 retry-after 时,等待时间可以写成:
delay = min(parsed_retry_after, max_delay_seconds)
没有该响应头时,使用带随机抖动的指数退避:
import random
def full_jitter_delay(attempt, base=1.0, cap=60.0):
upper = min(cap, base * (2 ** attempt))
return random.uniform(0, upper)
完整的重试判断应区分状态码:
RETRYABLE_STATUS = {429, 500, 502, 503, 504, 529}
def should_retry(status_code, attempt, max_attempts):
return (
status_code in RETRYABLE_STATUS
and attempt + 1 < max_attempts
)
认证失败、参数错误和不存在的模型通常不应按相同策略重试:
400 invalid_request_error -> 检查请求体
401 authentication_error -> 检查 API Key
403 permission_error -> 检查账户或模型权限
404 not_found_error -> 检查 URL 和模型名称
避免多个 worker 同时重试
固定等待 5 秒会产生同步重试:
00:00 worker-1 -> 429
00:00 worker-2 -> 429
00:00 worker-3 -> 429
00:05 worker-1 -> retry
00:05 worker-2 -> retry
00:05 worker-3 -> retry
加入随机抖动后,请求会被分散:
worker-1 delay=2.1s
worker-2 delay=4.8s
worker-3 delay=1.3s
还可以让所有 worker 共用一个限流器,而不是每个进程各算各的。如果部署了多个实例,需要把计数器放到 Redis 等共享存储中,并保证扣减操作是原子的。
local current = redis.call("GET", KEYS[1])
if not current then
redis.call("SET", KEYS[1], ARGV[1], "PX", ARGV[2])
return 1
end
if tonumber(current) >= tonumber(ARGV[3]) then
return 0
end
redis.call("INCRBY", KEYS[1], ARGV[1])
return 1
直连与中转的排查对比
| 调用路径 | 定位 429 时重点检查 | 建议记录的技术字段 |
|---|---|---|
| Anthropic 直连 | 官方账户层级、组织级限额、模型级响应头 | request-id、retry-after、输入与输出 Token |
| OpenRouter / ofox.io 聚合网关/中转 | 网关自身限流、上游模型限流、模型映射和错误转译 | 网关请求 ID、上游状态码、原始错误体、usage |
| 自建 API Gateway | Nginx、Envoy、云网关或 Redis 限流规则 | 限流规则名、实例 ID、客户端 IP、计数窗口 |
无论走哪条调用路径,都不要把所有 429 当成同一种故障。建议在内部错误对象里保留来源:
{
"status": 429,
"source": "upstream_provider",
"retry_after_seconds": 12,
"request_id": "req_xxx",
"attempt": 2,
"estimated_input_tokens": 148320
}
如果网关没有透传上游错误体,至少要区分:
source=local_limiter
source=self_hosted_gateway
source=aggregation_gateway
source=upstream_provider
source=unknown
长上下文任务怎么处理
对于代码审查、仓库分析和长文档任务,降低 worker 数量只是最后一道保护。更有效的是先减少单次输入量:
- 只发送相关文件和相关 diff。
- 删除重复的历史消息。
- 把仓库索引和具体代码片段分开。
- 对多个独立文件分批处理。
- 为系统提示词、工具定义和附件预留 Token。
- 限制单个任务允许占用的输入 Token。
- 对超大任务设置独立队列,避免阻塞短请求。
例如:
MAX_INPUT_TOKENS_PER_JOB = 120_000
if estimated_input_tokens > MAX_INPUT_TOKENS_PER_JOB:
raise JobTooLarge(
f"estimated input tokens {estimated_input_tokens} "
f"exceed per-job limit {MAX_INPUT_TOKENS_PER_JOB}"
)
如果必须拆分任务,要避免每一片都重复携带完整上下文。可以先生成一次结构化摘要,再让后续分片引用摘要和当前片段。
最后的排查顺序
遇到 HTTP 429 rate_limit_error,我现在按下面的顺序处理:
- 确认 429 来自本地限流器、网关还是上游。
- 读取
retry-after和可用的速率限制响应头。 - 分别计算 60 秒窗口内的 RPM、输入 TPM 和输出 TPM。
- 检查
max_in_flight、请求耗时和失败后的重试频率。 - 输入 Token 过高时,先缩短上下文或拆分任务。
- 请求数过高时,使用共享队列和请求桶限流。
- 没有
retry-after时,执行带随机抖动的指数退避。 - 为重试设置次数上限,并记录每次尝试的请求 ID。
关键不是单纯把并发调低,而是先弄清楚究竟是哪一个窗口被占满。请求数、输入 Token 和输出 Token 分开记录后,大多数 429 都能从日志中直接定位。
1001



被折叠的 条评论
为什么被折叠?



