Claude APIの429が出てレート制限が低すぎると感じたときの確認手順

Claude APIで429が返り続けると、まず「上限が低すぎるのでは」と疑いたくなります。ただ、429の原因は1つではありません。レート制限、月間の支出上限、ワークスペースの上限、急な利用増に対する加速制限が、どれも同じ429で返ってきます。

このページは、上限の引き上げを申請する前に確かめる順序をまとめた手順です。エラー本文とレスポンスヘッダーを見るだけで、原因の大半は絞り込めます。

最初にエラー本文とヘッダーを保存する

切り分けの材料は、失敗したレスポンスそのものにあります。リトライを回す前に、本文とヘッダーをログに残してください。

curl -i なら、ステータス行とヘッダーが本文と一緒に出ます。

curl -i 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": "'"$MODEL"'", "max_tokens": 64,
       "messages": [{"role": "user", "content": "ping"}]}'

SDKを使っているなら、例外からヘッダーと本文を取り出してログに出します。以下はPythonでの一例です。

import anthropic
 
client = anthropic.Anthropic()
try:
    client.messages.create(
        model=MODEL, max_tokens=64,
        messages=[{"role": "user", "content": "ping"}],
    )
except anthropic.RateLimitError as e:
    h = e.response.headers
    print("body:", e.body)
    print("retry-after:", h.get("retry-after"))
    print("workspace:", h.get("anthropic-workspace-id"))
    for k, v in h.items():
        if k.startswith("anthropic-ratelimit-"):
            print(k, v)

見るのは次の3点です。

• error.details.error_code の有無
• retry-after ヘッダーの有無
• anthropic-ratelimit-* ヘッダーのうち、remaining が0に近いもの

手順1: 月間の支出上限に当たっていないか

最初に外すべきは、支出上限の429です。レート制限と同じ rate_limit_error で返りますが、性質は逆で、待っても直りません。

支出上限の429には、次の特徴があります。

• retry-after ヘッダーが付かない
• Messages APIでは error.details.error_code が enforced_spend_limit_reached になる
• 本文に、再び使えるようになる日時(UTC)が入る

Start、Build、Scaleの各ティアには月間の支出上限があります。Startが500ドル、Buildが1,000ドル、Scaleが200,000ドルです。上限に達すると、翌月1日の0時(UTC)まで利用が止まります。SDKの自動リトライも失敗し続けます。

この場合に「レート制限が低い」は的外れです。ティアを上げるか、支出上限の引き上げを申請します。

自分で支出上限を設定している場合は、症状が変わります。その上限に達したときは429ではなく、HTTP 400の invalid_request_error です。429が出ているのに設定済みの上限を疑う必要はありません。ただしClaude Code用のワークスペースだけは別扱いで、上限を超えると retry-after 付きの429になることがあります。

手順2: どの上限を超えたのかを特定する

支出上限でなければ、レート制限そのものです。Messages APIのレート制限は、モデルのクラスごとに次の3種類で測られます。

429の本文には、どの上限を超えたかが書かれています。ヘッダーの remaining が0付近のものも同じ答えを指します。ここを特定しないまま「とにかく増枠」を申請しても、増やしたい対象が定まりません。

ヘッダー13種の読み方と分岐の組み方は、Claude APIレート制限ヘッダー13種の読み方と分岐ロジックにまとめています。

anthropic-ratelimit-tokens-* は、その時点で最も厳しい制限の値を示します。ワークスペースの上限に当たっていれば、組織の値ではなくワークスペースの値が出ます。表示値と組織の上限が食い違うときは、次の手順に進みます。

手順3: ワークスペースの上限に当たっていないか

組織の上限に余裕があるのに429が出るなら、ワークスペース単位で絞っている可能性があります。ワークスペースの上限を設定していなければ、組織の上限と同じ値になります。設定している場合、組織全体の上限がいくら余っていても、ワークスペースの上限が先に効きます。

確認は2段で行います。

1. レスポンスの anthropic-workspace-id ヘッダーで、APIキーがどのワークスペースに解決されたかを見る
2. そのワークスペースに上限が設定されているかを、ConsoleかRate Limits APIで見る

デフォルトのワークスペースには上限を設定できません。設定の読み出しはClaude Rate Limits APIで組織・ワークスペースのレート制限を確認するに、設定の手順はClaude APIでWorkspace単位のレート制限を設定する手順にあります。

ここで見つかる原因は、上限が低いのではなく、自分で絞った値に当たっているというものです。ワークスペースの上限を調整すれば済み、増枠申請は要りません。

手順4: 急な利用増による加速制限ではないか

通常のレート制限に余裕があっても、利用量が急に跳ね上がった直後は429が出ることがあります。これが加速制限(acceleration limits)です。

典型的な場面は、バッチ処理の初回実行、新機能のリリース直後、複数ジョブの同時起動です。避け方は、トラフィックを段階的に増やし、使い方を一定に保つことです。

この場合も、上限の引き上げでは直りません。ジョブの立ち上げを数分に分けて、並列数を少しずつ増やす設計に変えます。

手順5: 設計で消費を減らせないか

ここまでで本当にRPM、ITPM、OTPMのいずれかを超えていると分かったら、増枠を申請する前に、設計で下げられる分があるかを見ます。確認する項目は4つです。

容量はトークンバケット方式で補充されます。固定の間隔でリセットされるのではなく、上限に向かって連続的に回復します。待ち時間は retry-after の秒数に従ってください。それより早い再試行は失敗します。

キャッシュ率は、ConsoleのUsageページにある入力トークンのレート制限グラフで確認できます。グラフには、1時間ごとの最大の非キャッシュ入力トークン数、現在のITPM上限、入力トークンのキャッシュ率が並びます。出力側のグラフには、1時間ごとの最大出力トークン数と現在のOTPM上限が出ます。どの時間帯に上限へ近づいているかを、ここで確かめられます。

高速モードを使っているなら、標準のOpusとは別枠の上限が適用されます。切り分けはfast modeのレート制限は標準のOpusと別枠になる仕組みに書いています。

手順6: 上限が実際に足りないと判断するとき

支出上限でもワークスペースの絞りでも加速制限でもなく、キャッシュやバッチ化を済ませても、通常の利用量そのものが上限に届いている。その場合が、上限が低いと言える状態です。

引き上げの申請には条件があります。ヘルプセンターの案内では、現在の上限の50%以上を使っている状態になってから、Consoleで申請します。ティアと現在の上限は、ConsoleのSettings > Limitsで見られます。

申請の手順は次のとおりです。

1. ConsoleのRate limitsページで、現在のティアと上限を確認する
2. 同じ画面の「Request tier increase」から申請する
3. 急ぎの場合は、Anthropicのサポートに連絡する

Customティアは、アカウントチームと個別に上限を決めています。この場合はセールスへ連絡します。Claude Platform on AWSでは「Request tier increase」が使えず、アカウント担当者かサポートに連絡する形になります。連絡のときは、増やしたいモデル、モデルごとのピーク時の入力と出力のトークン数、入力のうちキャッシュや繰り返しが占める割合を添えます。

手順2で特定した上限の種類と、手順5で試した対策をまとめておくと、何を増やしたいのかが相手に伝わります。

切り分けの早見表

よくあるつまずき

• 429をすべてリトライで処理している: 支出上限の429は、リトライしても通りません。error_code で分岐してから待つ処理に入れます。SDKは一時的な失敗を、指数バックオフで既定2回まで自動リトライします。回数の変え方はClaude APIのエラーハンドリング設計に書いています。
• ヘッダーの平均だけを見ている: remaining は直近の状態です。ピーク時の値をログに残さないと、バーストが原因かどうかは判断できません。
• Claude Codeの429とAPIの429を混ぜている: サブスクリプションの上限とAPIの制限は別物です。Claude側で起きた場合はClaude rate limit(レート制限)エラーの対処を見てください。

よくある質問

429が出たら、すぐ増枠を申請してよいですか

申請の目安は、現在の上限の50%以上を使っていることです。使用率が低いのに429が出ているなら、上限の不足ではなく、手順1から5のどれかが原因です。

429と529はどう違いますか

429は組織側の上限に達したときのエラーです。529はAPI全体が混み合っているときに返ります。529の側にも、急な利用増に対しては加速制限による429が出る場合がある、という注意書きがあります。

まとめ

429に当たったら、順序は固定です。支出上限、上限の種類、ワークスペース、加速制限、設計の見直しの順に外し、最後まで残った場合にだけ増枠を申請します。この順に進めると、申請の中身も「どのモデルの、どの上限を、どれだけ」と具体的になります。