約 3 分で読めます

Claude APIの429を3種に分類する再試行設計

夜間バッチが全件 429 で失敗し、再試行ループが朝まで回り続けた。原因はレート制限ではなく、月次の支出上限への到達だった。Claude API の 429 は原因が複数あり、すべてを同じバックオフで処理すると、待っても回復しない障害を延々と再試行します。基本的な指数バックオフはLLM APIレート制限の対処設計で扱いました。この記事は「429 を分類してから再試行方針を決める」設計に絞ります。

Claude APIの429は何種類あり、どう見分けるのか

429は「レート制限」「月次の支出上限」「加速制限」の3種があり、retry-afterとerror_codeで判別します。

公式ドキュメントでは、429(rate_limit_error)は次の3つの原因で返ります。

  • レート制限: RPM・ITPM・OTPM のいずれかを超過した場合。retry-after ヘッダが付く場合は、その秒数だけ待ってから再試行する
  • 月次の支出上限: 利用ティアの上限(Start は 500 ドル、Build は 1,000 ドル、Scale は 20 万ドル)に到達した場合。retry-after は付かず、error.details.error_code が enforced_spend_limit_reached になる
  • 加速制限: 利用量が急増した場合。ドキュメントは、トラフィックを段階的に増やし一定の利用パターンを保つよう求めている

判別の優先順位は、まず error_code を見て支出上限を切り分け、次に retry-after の有無で待機時間を決める順です。メッセージ文字列の一致で判定せず、SDK の型付き例外と error_code を使います。

月次上限の429はなぜ再試行してはいけないのか

月次上限の429は翌月1日0時(UTC)まで回復せず、SDKの自動再試行も失敗し続けます。

支出上限の 429 は、翌月1日 00:00 UTC まで解消しません。公式SDKは一時的な失敗を既定で2回、指数バックオフで再試行しますが、この種類では何回再試行しても失敗します。設計上の対処は3点です。

  1. enforced_spend_limit_reached を検知したら再試行を打ち切り、ジョブを「保留」状態にして人に通知する
  2. 自社で設定した支出上限に達した場合は 429 ではなく 400(invalid_request_error)が返る点を、ハンドラで区別する
  3. 月次上限の接近を、利用量の集計から事前にアラートする

「待てば直る」エラーと「人が判断しないと直らない」エラーを分けることが、再試行設計の核心です。

レート制限を実際の上限値からどう設計するか

ITPMにはキャッシュ読み取りトークンが含まれないため、キャッシュ率が実効スループットを決めます。

ほとんどのモデルで、ITPM に数えられるのは input_tokens と cache_creation_input_tokens で、cache_read_input_tokens は数えられません。Start ティアの Claude Sonnet 5.5 は RPM 4,000、ITPM 200万、OTPM 40万です。キャッシュ率が80%なら、200万 ITPM で実質1,000万トークン相当の入力を処理できます。

OTPM は実際に生成されたトークンだけが数えられ、max_tokens は計算に入りません。上限を大きめに設定しても、レート制限上の不利益はありません。

また、レート制限は組織単位のトークンバケットで、固定間隔でリセットされません。60 RPM の制限が実際には1秒1リクエストとして働くことがあるため、短時間のバーストも 429 の原因になります。新規ワークロードを本番投入するときは、並列度を段階的に引き上げます。

ワークスペース上限はどうコードで管理するか

Rate Limits APIで、組織の上限読み取りとワークスペース上限の設定をコードから行えます。

Rate Limits API は Admin API の一部で、Admin API キーが必要です(ワークスペース用キーでは呼べません)。主な操作は次のとおりです。

  • GET /v1/organizations/rate_limits: 組織の上限をモデルグループ単位で取得する。model パラメータで特定モデルの所属グループも引ける
  • GET /v1/organizations/workspaces/{workspace_id}/rate_limits: ワークスペースの上書き設定を取得する。include_inherited=true で継承値も見られる
  • POST .../rate_limits/{rate_limit_id}: 値を整数で設定し、null で上書きを解除する

注意点が3つあります。ワークスペース値が組織の上限を超えても保存はされますが、適用されるのは低いほうです。変更の反映には約1時間かかります。組織全体の上限そのものは、この API では変更できません。

規模別の留意点(SMB / エンタープライズ)

SMB では、まず自社の支出上限を設定し、enforced_spend_limit_reached を検知したら再試行せず通知する、という2点から始めれば十分です。ワークスペースはアプリ単位で分け、暴走した1本が全体を止めない形にします。

エンタープライズでは、複数チームが同一組織の上限を共有します。プロビジョニング自動化に Rate Limits API を組み込み、ワークスペースごとの上限を宣言的に管理します。LLM ゲートウェイを置く場合も、ゲートウェイ側の上限値をハードコードせず、定期的に API から取得して同期させます。大規模な統制設計は RDE の領域です。

参考

まとめ

Claude API の 429 は、レート制限・月次支出上限・加速制限の3種に分け、error_code と retry-after で判別します。支出上限は再試行せず人に引き継ぎ、レート制限はキャッシュ率と並列度の段階的引き上げで抑えます。ワークスペース上限は Rate Limits API でコード管理できます。API 基盤の運用設計は、Kuu株式会社の導入支援サービスにご相談ください。

関連記事

LLM APIレート制限の対処設計——中小企業向け実装パターンClaude組織webhookの受信設計と取りこぼし対策Claude 128MB化で見直すLLMゲートウェイの上限設計Claude API 2026-10-21移行のゲートウェイ設計