Claude APIのITPM制限にキャッシュ読み込みがカウントされない仕組み

Claude APIのITPM制限はキャッシュ読み込み分を数えない

Claude APIのレート制限は、リクエスト数(RPM)・入力トークン数(ITPM)・出力トークン数(OTPM)の3種類をモデルクラスごとに管理します。多くのAPIプロバイダーは「トークン/分」の上限にキャッシュ済みトークンも含めますが、Claude APIのほとんどのモデルは違います。キャッシュから読んだ入力トークン(cache_read_input_tokens)はITPM制限にカウントされません。この設計により、実効スループットは表示された上限より大きく引き上がります。

対象はMessages APIのレート制限です。Message Batches APIやFiles API、Managed Agentsのレート制限には別枠の制限があり、本記事の計算式は対象外です。

3つのトークン種別とITPMへの算入ルール

Claude APIのレスポンスには、入力トークンを表す3つのフィールドがあります。ITPMに数えられるかどうかは、フィールドごとに決まっています。

合計の入力トークン数は次の式で求まります。

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

ここで注意が必要なのは、input_tokens が「リクエスト全体の入力トークン数」ではなく「直前のキャッシュブレークポイントより後ろの部分だけ」を表す点です。20万トークンのドキュメントをキャッシュして50トークンの質問だけを追加した場合、レスポンスの input_tokens は50になります。合計入力は20万50トークンですが、ITPMに効くのは input_tokens と cache_creation_input_tokens の合計だけです。ITPMはリクエスト開始時に見積もられ、実際に消費したトークン数に応じて途中で調整されます。

OTPM(出力トークン/分)は別の評価方式です。実際に生成された出力トークン数だけをリアルタイムに数え、max_tokens の値そのものは計算に入りません。max_tokens を大きく設定しても、レート制限上の不利益はありません。

ITPMは固定枠ではなく連続的に補充される

レート制限はトークンバケットアルゴリズムで動きます。固定の時間枠でリセットされるのではなく、上限まで容量が連続的に補充される方式です。

1分あたりの上限が決まっていても、もっと短い間隔で判定される場合があります。たとえば60RPMの上限は1秒あたり1リクエストとして扱われることがあり、短時間にまとめて送ると、分単位では上限内でも429が返ります。キャッシュでITPMを節約していても、送信間隔が偏っていればRPM側で先に止まります。

組織全体の利用量が急に増えた場合は、通常のITPM・RPM・OTPMとは別の急増抑制の制限(acceleration limits)でも429が返ります。トラフィックを段階的に増やし、一定のパターンを保つのが公式の回避策です。

キャッシュヒット率80%で実効ITPMが5倍になる計算

ITPM上限が200万トークン/分でキャッシュヒット率が80%のとき、1分あたり1,000万トークン(非キャッシュ200万+キャッシュ済み800万)を処理できます。キャッシュヒット率をhとすると、実効容量は次の式で近似できます。

実効ITPM ≈ ITPM上限 ÷ (1 - キャッシュヒット率)

Build tier(Claude Opus 5・Sonnet 5などで500万ITPM)の場合、ヒット率ごとの実効容量は次のとおりです。

上の式で計算すると、ヒット率を90%から95%に上げれば実効容量は2倍になります。これはBuild tierからScale tierへの引き上げ(500万から1,000万)と同じ倍率です。システムプロンプト・ツール定義・長文コンテキストなど、繰り返し送る内容をキャッシュ対象にすることが、実質的なレート制限の緩和策です。

10万トークンのプレフィックスでは、先にRPMが尽きる

式だけでは感覚が掴みにくいので、公式ドキュメントの使用例と同じ「10万トークンのキャッシュ済みコンテンツ+50トークンの質問」で、Build tierのSonnet 5(ITPM 500万・RPM 5,000)を計算します。

キャッシュが命中し続けると、ITPM消費は1リクエストあたり50トークンまで下がります。RPMの上限いっぱいの5,000回を送っても、ITPM消費は25万トークンです。上限の5%にとどまるので、この構成ではITPMを増やしても効果がなく、RPMが実質的な天井になります。

注意点は、キャッシュの寿命が既定で5分なことです。キャッシュは使われるたびに追加料金なしで更新されますが、5分以上リクエストが途切れると次のリクエストは再び書き込みになります。そのとき10万トークンは cache_creation_input_tokens として、ITPMにそのまま数えられます。

リクエストの間隔が5分を超えがちなワークロードには、1時間のTTL("ttl": "1h")があります。書き込みの価格は基準入力価格の2倍(5分TTLは1.25倍)なので、書き込みの頻度とITPMの余裕を見比べて選びます。

ティアごとのITPM上限とキャッシュの掛かり方

ITPM上限はティア(Start / Build / Scale)とモデルの組み合わせごとに決まります。代表的なモデルのITPM上限は次の通りです(RPM・OTPMは割愛)。

Fable 5.1とFable 5は合算の1バケットです(Mythos 5.1とMythos 5も、別の合算バケットを共有します)。Opus 4.8・4.7・4.6・4.5は合算、Sonnet 4.6・4.5も合算です。一方、Opus 5.5・Opus 5・Sonnet 5.5・Sonnet 5はそれぞれ別々の上限を持ちます。

レート制限はモデルごとに別々に適用されるので、複数モデルを並行して使えば、それぞれの上限まで同時に消費できます。キャッシュの非算入はHaiku 3.5を除く全モデルに掛かるため、Scale tierでヒット率80%なら、Opus 5の実効ITPMは5,000万トークン/分相当まで伸びます。

自分の組織の現在の上限は、ConsoleのRate limitsページか、Rate Limits APIで読み出せます。表の値は標準の上限で、組織によっては下回る場合があります。

429が出たときにキャッシュ起因かを切り分ける

キャッシュがITPMにどう効いているかは、Messages APIのレスポンスの usage オブジェクトで確認できます。リクエストごとに input_tokens / cache_creation_input_tokens / cache_read_input_tokens の内訳が分かります。

curl 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":[...]}' \
  | jq .usage

cache_creation_input_tokens と cache_read_input_tokens が両方0なら、そのリクエストはキャッシュされていません。原因の第一候補は最小キャッシュ長です。Fable 5.1・Opus 5.5・Opus 5・Sonnet 5.5は512トークン、Sonnet 5・Sonnet 4.6・4.5・Opus 4.8は1,024トークン、Opus 4.7は2,048トークン、Opus 4.6・4.5とHaiku 4.5は4,096トークンです。この長さに届かないプレフィックスは、cache_control を付けてもキャッシュされません。

429が出たら、次の順で原因を絞れます。

Haiku 3.5だけがcache_read_input_tokensをITPM消費に含める

「キャッシュはITPMを消費しない」というルールの例外が、Claude Haiku 3.5(Bedrock・Google Cloud以外では提供終了済み)です。Haiku 3.5は cache_read_input_tokens もITPM制限にそのまま算入します。Opus 5.5・Opus 5・Sonnet 5.5・Sonnet 5・Sonnet 4.x・Opus 4.x・Haiku 4.5・Fable 5.xは、キャッシュ読み込み分を除外します。

Haiku 3.5のITPM上限もStart tierで10万トークン/分と、他モデルの200万トークン/分より1桁以上小さい値です。Haiku 3.5からHaiku 4.5へ移行すれば、上限の数字そのものが20倍になります。

移行時に見落としやすいのが最小キャッシュ長です。Haiku 3.5は2,048トークン、Haiku 4.5は4,096トークンなので、2,048〜4,095トークンのプレフィックスは移行後にキャッシュ対象から外れます。その分は input_tokens として毎回ITPMに数えられます。移行後に429の出方が変わった場合は、Claude rate limitエラーの対処で切り分け手順を確認できます。

プロンプトキャッシュ自体の仕組みと課金・サブスク上限への効き方はClaudeのプロンプトキャッシュの仕組みで扱っています。本記事はそのうちレート制限(ITPM)への効き方だけを掘り下げています。

キャッシュ読み込みは料金とレート制限の両方で軽くなる

キャッシュ読み込みは、課金上も基準価格の10%(Claude Opus 5.5とSonnet 5.5は5%、Claude Fable 5.1・Mythos 5.1は2.5%)に割り引かれます。TPMを全トークン合算で管理するプロバイダーでは、キャッシュを使っても上限は変わりません。Claude APIではヒット率が上がるほど、単価と実効上限の両方が改善します。

まとめ — キャッシュ設計が先、引き上げ申請は後

ITPMは input_tokens と cache_creation_input_tokens だけを数えるので、429を受けたら上限の数字より先に、cache_read_input_tokens の比率とキャッシュの寿命(5分)を確かめるのが近道です。ヒット率が高い構成では、ITPMよりRPMのほうが先に天井になります。