Claude APIレート制限ヘッダー13種の読み方と分岐ロジック
Claude APIのレスポンスに付くanthropic-ratelimit-* ヘッダー13種の意味と、Workspace制限時にどちらの値が返るかの分岐ロジックを一覧で示します。
このTipsでできること
Claude APIのレスポンスヘッダーだけを見て、今のレート制限状態(上限・残量・リセット時刻)と、それがOrganization全体の制限なのかWorkspace個別の制限なのかを判定できるようになります(リクエストヘッダー側のanthropic-versionによるバージョン管理方針とはセットで押さえておきたい仕様です)。
429が返ったときに、待てば直るレート制限なのか、待っても直らない上限なのかを切り分ける手順も扱います。
標準の13ヘッダーと、あとから加わる2系統
標準で表に載るのは次の13種で、Messages APIのレスポンスに付くヘッダーです。Message Batches API・Managed Agents・Files APIの制限はMessages APIとは別枠になっています。retry-after は待ち時間を伝えるヘッダーなので、使う場面は429を受け取ったときです。
| ヘッダー | 意味 |
|---|---|
retry-after | 意味再試行までに待つ秒数。これより早い再試行は失敗する。tierの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 | 意味出力トークン制限が完全に補充される時刻 |
429の原因を探るとき、最初に見るのはヘッダー名の接頭辞です。接頭辞ごとに別の枠を指していて、足される条件も違います。
ヘッダー名の接頭辞でわかる枠の種類
anthropic-ratelimit-*(標準)
RPM・ITPM・OTPMの3種類の枠と、入力と出力の合算(
tokens)を示します。表の13種のうちretry-afterを除く12種がここに入ります。anthropic-priority-*(6種)
Priority Tierのコミットメントがあるモデルに
service_tier="auto"で送ると、入力と出力それぞれのlimit/remaining/resetが付きます。ヘッダーがあれば、上限超過でもPriority Tierの対象だったと判断できます。anthropic-fast-*(6種)
Opus 5.5・Opus 5・Opus 4.8で
speed: "fast"を指定したときの別枠です。入力と出力それぞれのlimit/remaining/resetが付き、標準のOpusの制限とは別に数えます。
fast modeのページには、Priority Tierのコミットメントとは併用できないと書かれています。標準13種にPriority Tierの6種を足した19種が最大で、fast modeを使う場合は標準の枠にfastの6種が加わる、と読み分けます。
残量はどの制限の値か — WorkspaceとOrganization
anthropic-ratelimit-tokens-*(接頭辞なしの3つ)は、現在有効な制限のうち最も厳しいものの値を返します。Organization全体のper-minute token制限は超えていないがWorkspace個別の制限を超えている場合、このヘッダーにはWorkspace側の値が入ります。Workspace制限が効いていないリクエストでは、入力と出力の合計の残量が返ります。
同じ anthropic-ratelimit-tokens-remaining でも、リクエストによって「Workspaceの残量」か「Organizationの残量」かが変わるわけです。どちらかを見分けるには、同じレスポンスの anthropic-workspace-id ヘッダーを使います。
HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ上はWorkspaceのドキュメントに載っているレスポンスヘッダーの例です。値は wrkspc_ で始まるIDで、APIキーまたはアクセストークンが解決されたWorkspaceを指します。デフォルトWorkspaceのキーでも付きます。Admin APIのリクエストのように、資格情報がWorkspaceに解決されない場合や、認証が終わる前に失敗した401のような場合は付きません。
Workspace制限の設定には前提があります。デフォルトWorkspaceには制限を設定できません。未設定のWorkspaceはOrganizationの値と同じになり、Workspace制限の合計がOrganizationの制限を超えていても、Organization全体の制限は常に効きます。ドキュメントの例では、Organizationの制限が入力40,000トークン/分のとき、あるWorkspaceだけ30,000トークン/分に絞れます。残りの10,000は他のWorkspaceが使えます。
Workspaceのロール構成やAPIキーのスコープはClaude Workspacesのロール継承とAPIキーのスコープで扱っています。
残量の数字を読み違えやすい4点
残量ヘッダーは、そのまま使うと実際の余裕とずれる場面があります。
- 丸め:
tokens/input-tokens/output-tokensのremainingは1,000単位に丸められます。上限に近づいた検知には足りますが、消費量の正確な積算には向きません。正確に追うなら、レスポンスのusage(input_tokens/output_tokens/cache_creation_input_tokens/cache_read_input_tokens)を自前で足し上げます - モデルごとの枠: 制限はモデルごとに別々に適用されます。Opus 5.5とOpus 5はそれぞれ別の枠です。Opus 4.8・4.7・4.6・4.5は合算の1つの枠で、Sonnet 5.5とSonnet 5が別枠、Sonnet 4.6と4.5が合算、Fable 5.1とFable 5が合算という分け方もあります。複数モデルを並行して呼ぶ構成では、ログにモデル名を添えて残さないと、どの枠の残量か分からなくなります
- キャッシュ: ITPMに数えるのは
input_tokens(最後のキャッシュブレークポイントより後)とcache_creation_input_tokensで、cache_read_input_tokensは大半のモデルで数えません。たとえばキャッシュ済み文書が200,000トークン、質問が50トークンなら、input_tokensは50で、input-tokens-remainingの減りも主にその分です。Haiku 3.5(BedrockとGoogle Cloud以外では提供終了)だけはcache_read_input_tokensもITPMに含まれます。なお、ITPMはリクエストの開始時に見積もられ、処理中に実際の入力トークン数へ補正されます - 出力: OTPMは出力トークンが生成されるそばからリアルタイムに数えられ、実際に生成された分だけが対象です。
max_tokensは計算に入らないため、大きな値を指定してもoutput-tokens-remainingは減りません
inference_geo を "us" にしても "global" にしても、同じレート制限のプールから引かれます。地域ごとに別の枠は持たない扱いです。
429が来たときの切り分け
429は1種類ではなく、上限に当たった理由で待ち方が変わります。
| 状況 | ステータスとtype | retry-after | 見分け方 |
|---|---|---|---|
| RPM・ITPM・OTPMの超過 | ステータスとtype429 rate_limit_error | retry-afterあり | 見分け方本文にどの制限を超えたかが出る。指定秒数を待つ |
| tierのspend cap到達 | ステータスとtype429 rate_limit_error | retry-afterなし | 見分け方error.details.error_code が enforced_spend_limit_reached |
| 自分で設定したspend limitに到達 | ステータスとtype400 invalid_request_error | retry-after— | 見分け方メッセージが You have reached your specified API usage limits で始まる |
| Claude Codeワークスペースの上限超過 | ステータスとtype429 | retry-afterあり | 見分け方Claude Codeワークスペースに設定した上限のとき |
spend capの429は、翌月1日00:00 UTCまで、または上限を引き上げるまで失敗し続けます。SDKの自動リトライも同じく失敗します。Workspace単位のspend limitに当たった場合は、メッセージの冒頭が You have reached your specified workspace API usage limits になります。ティア別の金額と引き上げ手順はClaude APIの月間支出上限にあります。
落とし穴は、retry-after の有無だけで分岐すると、Claude Codeワークスペースの上限超過の429が通常のレート制限と同じ扱いになる点です。Claude Codeワークスペースの429には retry-after が付くため、retry-after のないspend capの429とは区別できます。一方、通常のレート制限の429とはヘッダーだけでは区別できません。
使用量が急に増えた組織には、acceleration limits(急増に対する制限)による429が出ることもあります。トラフィックは段階的に増やし、使い方を一定に保つのが避け方です。
429とは別に、529 overloaded_error はAPI全体が混み合っているときに返ります。レート制限ヘッダーの値を見ても原因は分かりません。
バックオフの組み方
公式SDKは、接続エラー・レート制限・5xxを指数バックオフで既定2回まで自動的に再試行し、retry-after があればその値に従います。回数は max_retries(TypeScript・Java・PHPは maxRetries)で変えられます。自前で組むときは次の順に判定します。
429を受け取ってからの判定順
- 1
spend capかどうかを先に見る
error.details.error_codeがenforced_spend_limit_reachedなら、待っても復旧しません。リトライを止め、上限の引き上げか翌月1日00:00 UTCまで別の経路に回します。 - 2
retry-after の秒数だけ待つ
指定秒数より早い再試行は失敗します。固定の短い間隔でリトライすると、失敗が続くだけです。
- 3
remaining を見て429の手前で間隔を広げる
anthropic-ratelimit-input-tokens-remainingやanthropic-ratelimit-requests-remainingをリクエストごとに記録し、上限の一定割合(たとえば10%)を下回ったらリクエスト間隔を広げます。 - 4
reset は完全復旧の時刻として扱う
レート制限はトークンバケット方式で、固定間隔でリセットされず連続的に補充されます。
*-resetはRFC 3339形式の「完全に補充される時刻」です。容量は連続的に補充されるため、remainingを見て必要な量が戻った時点で再開する設計も取れます。
上限そのものを知りたいときはRate Limits API
ヘッダーが教えるのは、リクエストを送った時点の状態だけです。リクエストの前に上限値を知りたいとき、Workspaceごとの上書き設定を棚卸ししたいときは、Admin API配下のRate Limits APIを使います。
ヘッダーとRate Limits APIの役割
レスポンスヘッダー
「このリクエストが、今どの制限にどれだけ近いか」を返します。リトライの待ち時間やアラートの閾値に向きます。
Rate Limits API
Organizationに設定された上限と、Workspaceごとの上書きを返します。日々のリクエスト処理ではなく、設定の監査や自動プロビジョニングの検証向けです。
エンドポイントは /v1/organizations/rate_limits(Organization)と /v1/organizations/workspaces/{workspace_id}/rate_limits(Workspace)の2つです。使える資格情報は、Admin APIキー、org:admin スコープのOAuthトークン、Workspaceに紐づかない個人またはサービスアカウントのキーで、Workspaceに紐づくAPIキーでは呼べません。
返り値の読み方にはいくつか癖があります。
- Organizationのエンドポイントは、モデル群ごとの
group(IDはrlg_で始まる)を返す。modelsに、そのグループの上限が適用されるモデルIDとエイリアスが並ぶので、手元のモデル名がどの枠に入るかをここで調べられる modelパラメーターで1モデルに絞れるのはOrganizationのエンドポイントだけで、どのグループにも当たらない文字列は404になる- Workspaceのエンドポイントは上書きだけを返す。レスポンスに現れないグループは、Organizationの値を引き継ぐ(無制限ではない)。グループが現れても、
limitsに無い種別は同様に引き継ぐ - デフォルトWorkspaceは上書きを持てないため、このエンドポイントに行がない。上限はOrganizationのエンドポイントで読む
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-opus-5-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 の値をログに残し、閾値を下回ったらアラートを出す構成が簡単です。
社内ネットワークからこのリクエストが通らないときは、Claude APIのIPアドレスをファイアウォールに許可登録する手順が手がかりになります。x-api-key 以外の認証ヘッダーが必要になるキーの種類はClaude APIの認証方式まとめにあります。
fast modeの対象外モデルで起きること
fast modeに対応するのはOpus 5.5・Opus 5・Opus 4.8です。Opus 4.7で speed: "fast" を指定するとリクエストがエラーになります。Opus 4.6では例外的にエラーにならず、標準速度で処理されます。
fast modeが効いたかどうかは、レスポンスの usage.speed("fast" か "standard")で決まります。Opus 4.6ではこの値が "standard" になります。fast modeの上限超過や容量不足は、429か529で返ります。SDKはこれらのリクエストも既定で最大2回まで自動的に再試行します。最初のfastリクエストで max_retries を 0 にすると、再試行せずにレート制限エラーをそのまま受け取れます。
まとめ
残量ヘッダーを読む前に anthropic-workspace-id でどの枠の値かを決め、モデルごと・キャッシュの扱いごとにずれを織り込むと、アラートの閾値が実態に合います。429は retry-after の有無に加えて error_code とメッセージで原因を決め、待つか止めるかを選びます。