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

> Claude APIの429はレート制限・月次支出上限・加速制限の3種で、再試行の可否が異なる。retry-afterとerror_codeで判別し、ワークスペース上限をRate Limits APIで管理する設計を示す。

- Canonical: https://kuucorp.com/blog/claude-api-429-classification-spend-cap-workspace-limits-design/
- Date: 2026-10-31
- Last modified: 2026-10-31
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
夜間バッチが全件 429 で失敗し、再試行ループが朝まで回り続けた。原因はレート制限ではなく、月次の支出上限への到達だった。Claude API の 429 は原因が複数あり、すべてを同じバックオフで処理すると、待っても回復しない障害を延々と再試行します。基本的な指数バックオフは[LLM APIレート制限の対処設計](/blog/llm-api-rate-limit-handling-smb/)で扱いました。この記事は「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](https://kuucorp.com/services/rde/) の領域です。

## 参考

- [Rate limits（Claude API Docs）](https://platform.claude.com/docs/en/api/rate-limits)
- [Claude API errors（Claude API Docs）](https://platform.claude.com/docs/en/api/errors)
- [Rate Limits API（Claude API Docs）](https://platform.claude.com/docs/en/manage-claude/rate-limits-api)

## まとめ

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