Claude API 429 rate_limit_error — 原因と確実な対処法

Claude API の 429 は、Anthropic の毎分制限（リクエスト数、入力トークン数、出力トークン数）のいずれかを超えたことを意味します。解決策は、単に「長く待つ」ことではありません。retry-after を尊重し、ジッター付きバックオフを追加し、バーストを平準化することです。完全な対処法を示します。

エラー

response (HTTP 429)

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

原因と対処法の概要

原因	対処法
Requests-per-minute (RPM) 制限に到達	クライアント側でリクエストをキューに入れ、リトライ前に retry-after ヘッダーを尊重します。
Input-tokens-per-minute (ITPM) に到達 — 大きなプロンプト、少ないリクエスト	取得したコンテキストを削減し、対応プランではプロンプトキャッシュを有効にして、キャッシュ済みトークンがカウントされないようにします。
Output-tokens-per-minute (OTPM) に到達	max_tokens を現実的に設定します。長い生成では、OTPM が最初の上限になることがよくあります。
バーストトラフィック（cron が :00 にすべて実行される）	スケジュールにジッターを追加し、バッチジョブを1分間に分散します。

リトライ前にレスポンスを読む

Anthropic は待機すべき秒数を retry-after ヘッダーで返し、エラーメッセージには超過した制限が示されます。読まずに即時リトライすると、1回の 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 の呼び出しに実際にかかる費用を、Anthropic の公式価格と当社の価格を並べて確認するには、 Anthropic Claude API料金表.

よくある質問

Anthropic のティアをアップグレードすれば 429 はなくなりますか？

上位ティアでは毎分の上限が引き上げられるため 429 は減りますが、どのような固定上限でも、突発的な負荷によって達する可能性があります。ティアに関係なく、本番コードにはバックオフが必要です。

429 をすぐにリトライすべきですか？

いいえ。retry-after ヘッダーを尊重してください（ない場合はジッター付き指数バックオフを使用します）。即時リトライはレート制限期間を延ばし、より長いロックアウトに発展する可能性があります。

失敗した 429 リクエストには料金がかかりますか？

Anthropic は拒否されたリクエストに課金せず、Kunavo も同様です。失敗したリクエストには決して課金されません。429 のコストは金額ではなくレイテンシーです。