Claude API 429 rate_limit_error——原因及可靠的修复方法

Claude API 返回 429，表示你超过了 Anthropic 的某项每分钟限制——请求数、输入令牌数或输出令牌数。解决方法很少只是“等待更久”：你需要遵守 retry-after、加入带抖动的退避，并平滑流量峰值。以下是完整方案。

错误

响应（HTTP 429）

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

原因和解决方法一览

原因	解决方法
达到每分钟请求数（RPM）限制	在客户端将请求排队；重试前遵守 retry-after 请求头。
达到每分钟输入令牌数（ITPM）限制——提示词很大，请求很少	减少检索到的上下文；在受支持的方案中启用提示词缓存，使缓存令牌不再计入你的限制。
达到每分钟输出令牌数（OTPM）限制	合理设置 max_tokens——对于较长的生成，OTPM 通常是第一个达到的上限。
流量突发（cron 在 :00 时一次性触发所有任务）	为调度加入抖动；将批处理作业分散到整分钟内。

重试前先读取响应

Anthropic 会返回 retry-after 请求头，其中包含需要等待的秒数，错误消息也会说明你超过了哪项限制。不读取它就立即重试，是让单个 429 变成 429 风暴的原因。

加入带抖动的指数退避

只重试可重试的状态码（429、500、529），绝不要重试身份验证或验证错误。这段代码无需修改即可直接用于 Anthropic，也可用于任何兼容 OpenAI 的端点：

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

减少令牌，而不只是减少请求

如果消息指出的是令牌限制，仅靠退避无法解决问题。减少检索片段、限制 max_tokens，并启用提示词缓存——在输入速率的 10% 下发送一个大型且稳定的系统提示词，也能缓解 ITPM 压力。

如果你通过 Kunavo 调用

通过 Kunavo 调用 Claude 不会神奇地消除速率限制，但会改变故障成本：失败的请求（包括 429）永远不会计费，并且按密钥显示的使用量仪表板会明确指出是哪一个密钥和模型产生突发流量，便于你进行平滑处理。上面的退避代码可以原样使用——只有 base_url 不同。速率限制是吞吐量上限，不是价格——要了解 Claude 调用实际每 1M 令牌的成本，以及 Anthropic 官方价目表与我们的价格对比，请参阅 Anthropic Claude API 价格列表.

常见问题

升级 Anthropic 层级后，429 会消失吗？

更高层级会提高每分钟上限，因此 429 会变少，但任何固定上限都可能被流量突发击穿。无论使用哪个层级，生产代码都需要退避。

应该立即重试 429 吗？

不应立即重试——请遵守 retry-after 请求头（如果没有该请求头，则使用带抖动的指数退避）。立即重试会延长限流窗口，并可能升级为更长时间的锁定。

失败的 429 请求会产生费用吗？

Anthropic 不会对被拒绝的请求收费，Kunavo 也不会——失败的请求永远不会计费。429 的成本是延迟，而不是金钱。