Claude APIレート制限ヘッダー13種の読み方と分岐ロジック
Claude APIのレスポンスに付くanthropic-ratelimit-* ヘッダー13種の意味と、Workspace制限時にどちらの値が返るかの分岐ロジックを一覧で示します。
このTipsでできること
Claude APIのレスポンスヘッダーだけを見て、今のレート制限状態(上限・残量・リセット時刻)と、それがOrganization全体の制限なのかWorkspace個別の制限なのかを判定できるようになります(リクエストヘッダー側のanthropic-versionによるバージョン管理方針とはセットで押さえておきたい仕様です)。
標準の13ヘッダー一覧
Claude APIの各レスポンスには、レート制限の現在状態を示すヘッダーが付与されます。Priority Tierを使っていない通常の利用では、次の13種が返ります。
| ヘッダー | 意味 |
|---|---|
retry-after | 意味再試行までに待つべき秒数。spend cap到達時の429には付かない |
anthropic-ratelimit-requests-limit | 意味期間内に許可される最大リクエスト数 |
anthropic-ratelimit-requests-remaining | 意味レート制限に達するまでの残りリクエスト数 |
anthropic-ratelimit-requests-reset | 意味リクエスト制限が完全に補充される時刻(RFC 3339形式) |
anthropic-ratelimit-tokens-limit | 意味期間内に許可される最大トークン数(最も厳しい制限の値) |
anthropic-ratelimit-tokens-remaining | 意味レート制限に達するまでの残りトークン数(1,000単位で丸め) |
anthropic-ratelimit-tokens-reset | 意味トークン制限が完全に補充される時刻 |
anthropic-ratelimit-input-tokens-limit | 意味期間内に許可される最大入力トークン数 |
anthropic-ratelimit-input-tokens-remaining | 意味残りの入力トークン数(1,000単位で丸め) |
anthropic-ratelimit-input-tokens-reset | 意味入力トークン制限が完全に補充される時刻 |
anthropic-ratelimit-output-tokens-limit | 意味期間内に許可される最大出力トークン数 |
anthropic-ratelimit-output-tokens-remaining | 意味残りの出力トークン数(1,000単位で丸め) |
anthropic-ratelimit-output-tokens-reset | 意味出力トークン制限が完全に補充される時刻 |
このほかに、Priority Tierを契約している組織にだけ、anthropic-priority-input-tokens-limit / -remaining / -reset と anthropic-priority-output-tokens-limit / -remaining / -reset の6ヘッダーが追加で返ります。標準13種と合わせて最大19ヘッダーになりますが、Priority Tier契約が無ければこの6つは現れません(ネットワーク境界側の設定はClaude APIのIPアドレスをファイアウォールに許可登録する手順が参考になります)。
ヘッダーはモデルごとに別の値を返す
Claude APIのレート制限はモデルクラスごとに独立しています。Opus 5・Sonnet 5・Haiku 4.5はそれぞれ別のRPM/ITPM/OTPM上限を持ち、レスポンスヘッダーもそのリクエストで使ったモデルの値を返します。つまり、同じ組織でOpus 5とSonnet 5を並行して呼んでいる場合、片方のレスポンスヘッダーだけを見て「全体の残量」と誤解すると、実際にはまだ余裕があるモデルの制限を早めに切り上げてしまいます。複数モデルを使い分けるアプリケーションでは、モデルごとにヘッダーの値を別々にログへ残す必要があります。
anthropic-ratelimit-*-remaining 系の値は1,000単位に丸められて返る点にも注意が必要です。丸めがかかるため、このヘッダーだけでは正確な残量は分かりません。上限にかなり近づいている状況を検知する用途には十分ですが、正確な消費量を追跡したいなら、リクエストごとのレスポンス usage フィールド(input_tokens / output_tokens / cache_creation_input_tokens / cache_read_input_tokens)を自前で積算するほうが確実です。
anthropic-ratelimit-tokens-*はどちらの制限値を返すか
anthropic-ratelimit-tokens-*(接頭辞なしの3つ)は、現在有効な制限のうち最も厳しいものの値を返します。たとえばOrganization全体のper-minute token制限は超えていないがWorkspace個別のper-minute token制限を超えている場合、このヘッダーにはWorkspace側の値が入ります。Workspace制限が設定されていない、または該当しないリクエストでは、入力トークンと出力トークンの合計の残量が返ります。
つまり同じ anthropic-ratelimit-tokens-remaining でも、リクエストによって「Workspace個別の残量」なのか「Organization全体の残量」なのかが変わります。どちらが返っているかを区別したい場合は、同じレスポンスに含まれる anthropic-workspace-id ヘッダー(/api/overview のレスポンスヘッダー節で定義)を併せて読みます。このヘッダーには、そのAPIキーまたはアクセストークンが解決されたWorkspaceのIDが入るため、リクエストがどのWorkspaceにカウントされたかを特定できます。
ヘッダーの使い分け早見表
用途によって見るべきヘッダーが変わります。
| 用途 | 見るヘッダー | 理由 |
|---|---|---|
| 429の再試行待ち時間を決める | 見るヘッダーretry-after | 理由秒数がそのまま使える(spend cap到達時は付かないため別処理が必要) |
| ITPM上限に近いか監視する | 見るヘッダーanthropic-ratelimit-input-tokens-remaining | 理由tokens系より粒度が細かく、キャッシュ非算入分を反映した実際の残量が分かる |
| どのWorkspaceの制限に当たったか特定する | 見るヘッダーanthropic-workspace-id + anthropic-ratelimit-tokens-* | 理由Workspace個別制限とOrganization制限のどちらが効いたかを突き合わせられる |
| リクエスト数の上限監視 | 見るヘッダーanthropic-ratelimit-requests-remaining | 理由RPM上限はモデルごとに独立しているため、モデル単位でこのヘッダーを追う |
リセット時刻ヘッダーの使い道
anthropic-ratelimit-*-reset 系のヘッダーはRFC 3339形式の絶対時刻で返るため、Unixタイムスタンプへの変換や現在時刻との差分計算をアプリケーション側で行えば、次に上限が完全に補充されるまでの残り秒数が分かります。レート制限はトークンバケット方式で連続的に補充されるため、reset時刻はあくまで「完全に満タンになる時刻」であり、それより前でも部分的に補充された分から新しいリクエストを送れます。バックオフ戦略を組むときは、reset時刻まで丸ごと待つのではなく、remaining の値が一定量に回復した時点で再開する設計のほうが待機時間を短縮できます。
resetヘッダーを使ったバックオフの実装手順
トークンバケット方式の性質を踏まえると、バックオフ処理は次の3段階で組むのが実装しやすい構成です。
- 429を受け取ったら
retry-afterの有無を先に見る: 付いていればその秒数だけ待って再試行する。付いていなければspend cap到達なので、retry-after待機ではなく別のエラーハンドリングに分岐する retry-afterが無い429以外の場面ではremainingを監視して先回りする:anthropic-ratelimit-input-tokens-remainingやanthropic-ratelimit-requests-remainingの値をリクエストのたびにログへ残し、上限の一定割合(たとえば10%)を下回った時点でリクエスト間隔を自動的に広げる。429を受け取ってから待つより、429自体を発生させない運用に近づけられます- reset時刻は「完全復旧の上限」として扱う:
anthropic-ratelimit-tokens-resetまでの残り秒数を計算しても、それを丸ごと待つ必要はありません。トークンバケットは連続的に補充されるため、次のリクエストで返ってきたremainingが実用上足りる量まで回復していれば、reset時刻を待たずに再開できます
この3段階を組み合わせると、reset時刻までの固定待機よりも実行速度を落とさずに429の再発を抑えられます。
Priority Tierとfast modeのヘッダーは別枠で加わる
Priority Tierを契約している組織では、標準13ヘッダーに加えて anthropic-priority-input-tokens-* と anthropic-priority-output-tokens-* の6ヘッダーが常に返ります。この2系統は完全に独立した制限であり、標準の anthropic-ratelimit-* ヘッダーがまだ余裕を示していても、Priority Tier側の枠を使い切っていれば別扱いのレート制限に触れます。逆にPriority Tier側に余裕があっても、標準側の制限を超えていれば429になります。
Opus 5・Opus 4.8で speed: "fast" を指定するfast mode(research preview)を使う場合は、さらに anthropic-fast-* という別系統のヘッダーが追加されます。これは標準のOpusレート制限ともPriority Tierとも別枠の制限で、fast modeを使い始めた直後は「なぜ429が増えたのか」がヘッダーの種類を区別しないと分かりにくくなります。429のエラー原因を切り分けるときは、レスポンスに含まれるヘッダー名の接頭辞(anthropic-ratelimit- / anthropic-priority- / anthropic-fast-)を先に確認し、どの制限系統に触れたのかを特定するのが最初の一手です。
curlでヘッダーを確認する
実装に組み込む前に、まずレスポンスヘッダーだけを見て挙動を確認するのが早道です。
curl -sD - 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":"claude-sonnet-5","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}' \
-o /dev/null | grep -i "anthropic-ratelimit\|retry-after\|anthropic-workspace-id"-D - でヘッダーを標準出力に落とし、grep で該当ヘッダーだけを抜き出します。CIやモニタリングに組み込む場合は、anthropic-ratelimit-input-tokens-remaining の値をログに残し、上限の閾値を下回ったらアラートを出す構成が簡単です。APIキーの種類によって x-api-key 以外の認証ヘッダーが必要になるケースはClaude APIの認証方式まとめを参照してください。
ヘッダーとRate Limits APIの使い分け
ヘッダーは「直前のリクエストを送った瞬間の状態」しか教えてくれません。リクエストを送る前に上限値そのものを確認したい、あるいはWorkspaceごとの上書き設定を一覧で見たい場合は、Admin API配下のRate Limits API(/v1/organizations/rate_limits と /v1/organizations/workspaces/{workspace_id}/rate_limits)を使います。この2つのエンドポイントはAdmin APIキーまたは org:admin スコープのOAuthトークンが必要で、Workspace個別のAPIキーでは呼び出せません。
ヘッダーとRate Limits APIは役割が異なります。ヘッダーは「今この瞬間、このリクエストがどの制限にどれだけ近いか」を見るための実行時シグナルで、実装のリトライロジックやアラートに向きます。Rate Limits APIは「組織全体でWorkspaceごとにどんな上書き設定が入っているか」を棚卸しする監査用途に向いており、日々のリクエスト処理には使いません。Workspace側にレート制限の上書きが設定されていない場合、そのWorkspaceのグループはAPIのレスポンスに現れず、Organizationの値をそのまま継承します。
実装でよくある誤読
ヘッダーを実装に組み込むときにありがちな誤解が3つあります。
anthropic-ratelimit-tokens-remainingを「入力+出力の合計残量」と決め打ちする: Workspace制限が効いているリクエストでは、これがWorkspace側の値に置き換わっている場合があります。anthropic-workspace-idを併読しないと、どちらの数値かを取り違えます- 全モデル共通の残量だと思い込む: 前述の通りモデルごとに独立した値なので、Opus用に書いたアラート閾値をSonnetのレスポンスにもそのまま適用すると、実際の余裕度とずれた警告が出ます
- 429のたびに同じリトライ間隔を使う:
retry-afterが付く通常のレート制限と、付かないspend cap到達を区別せずに固定秒数でリトライすると、spend cap到達時は待っても無駄なリクエストを繰り返すことになります
429を受け取ったときの分岐処理
429エラーには2種類あり、ヘッダーの有無で見分けられます。
- レート制限による429:
retry-afterヘッダーが付く。指定秒数を待てば再試行できる - 月間spend capによる429:
retry-afterヘッダーが付かない。翌月1日00:00 UTCまで、もしくは上限引き上げまで再試行しても失敗し続ける
リトライロジックを書くときは、retry-after の有無を最初に判定してから待機時間を決めるのが安全です。SDKの自動リトライも、spend cap到達時は失敗を返し続けるため、error.details.error_code が enforced_spend_limit_reached かどうかも合わせて確認すると、無駄な再試行ループを避けられます。
fast modeの対応状況はモデルによって異なります。Opus 4.7はfast modeに非対応で、anthropic-fast-* ヘッダーはそもそも付きません。Opus 4.6で speed: "fast" を指定した場合はリクエスト自体は通りますが、標準速度で処理されるため anthropic-fast-* ヘッダーは意味を持ちません。fast modeが実際に効くのは前述のOpus 5・Opus 4.8のみで、429の原因を切り分けるときはまず対象モデルがこの2つに含まれるかを確認してから、ヘッダーの有無を判断する必要があります。
まとめ
Claude APIのレート制限ヘッダーは、Priority Tier契約が無ければ13種類、契約があれば19種類が返ります。fast modeを併用している場合はさらに anthropic-fast-* 系統が加わり、合計で3系統のヘッダーを扱うことになります。
実装で押さえるべき分岐は2点です。1つ目は anthropic-ratelimit-tokens-* で、最も厳しい制限(WorkspaceまたはOrganization)の値を動的に返すため、どちらの制限に当たったのかは anthropic-workspace-id と組み合わせて初めて特定できます。2つ目は429時の retry-after の有無で、これによりレート制限とspend cap到達を区別してリトライ処理を分岐させます。
監視を組むなら anthropic-ratelimit-input-tokens-remaining を軸に据え、閾値を下回った時点でリクエスト間隔を広げる設計にするのが実装上の最短ルートです。Workspaceのロール構成やAPIキーのスコープについてはClaude Workspacesのロール継承とAPIキーのスコープで扱っています。