コンテキストウィンドウがオーバーフローしたときのClaude APIの挙動

コンテキストウィンドウのオーバーフローには2パターンある

Claude APIでコンテキストウィンドウの上限を超えたとき、応答は入力が超えているかと生成中に超えるかで完全に分かれます。前者は常に400エラーで即座に弾かれ、後者は後発の対応モデルに限り、途中まで生成した結果をstop_reason: "model_context_window_exceeded"として返します。この違いを把握していないと、片方の対処だけを実装して残り半分のケースをエラーとして誤扱いすることになります。

入力だけで上限を超えている場合は400エラー固定

入力(system prompt・messages・tool定義・画像やドキュメントを含むすべて)の時点でモデルのコンテキストウィンドウを超えていれば、全モデル共通でAPIは400の invalid_request_error(prompt is too long)を返します。ここに例外はありません。事前にトークン数を見積もっていないと、リクエストを送信してから初めて失敗に気づくことになります。事前見積もりにはトークンカウンティングAPIを使い、実際にメッセージを送る前にどれだけのトークン数になるかを確認します。これは課金を伴わない軽い呼び出しで、入力オーバーフローかどうかをリクエスト送信前に判定できる唯一の確実な方法です。

生成中に上限を超えた場合はモデル世代で挙動が変わる

問題は「入力自体は上限内だが、max_tokensまで出力させようとすると上限を超える」ケースです。ここでの挙動は世代で二分されます。

model_context_window_exceeded は現状SDKの beta 名前空間にのみ型定義があるため、Sonnet 4.5以降は追加ヘッダーなしでこの値を受け取れますが、コード側は client.beta.messages 経由の呼び出しと Beta 接頭辞の型を使う必要があります。

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-opus-5",
    "max_tokens": 20000,
    "messages": [{"role": "user", "content": "Large input that uses most of context window..."}]
  }' | jq '.stop_reason'

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=20000,
    messages=[{"role": "user", "content": "..."}],
)
 
if response.stop_reason == "model_context_window_exceeded":
    # レスポンスは有効だが、max_tokensに届く前にコンテキストウィンドウで打ち切られた
    print("context window limit reached")

この挙動を利用した実装パターン

model_context_window_exceeded は単なるエラー通知ではなく、入力サイズを正確に計算せずに「取れるだけ最大トークンを取る」実装を可能にします。max_tokens に大きめの値をあらかじめ指定しておけば、実際にどこまで出力できるかはコンテキストウィンドウの残量が決めてくれるため、リクエスト前のトークンカウンティングを省略できます。この実装パターンのコード例は入力サイズ不明でも最大出力を引き出すmodel_context_window_exceeded活用法で扱います。

モデルごとのコンテキストウィンドウサイズと上限トークン

Claude Fable 5.1・Claude Mythos 5.1・Claude Fable 5・Claude Mythos 5・Claude Opus 5・Claude Opus 4.8・Claude Opus 4.7・Claude Opus 4.6・Claude Sonnet 5・Claude Sonnet 4.6・Claude Mythos Previewの1M対応モデル群と、Claude Sonnet 4.5を含む200kモデル群の2系統に分かれます(実務での使い方はClaude 1Mコンテキストの実務活用を参照)。1Mトークン対応モデルでは1Mが既定値で、ベータヘッダーは不要、長文コンテキストのリクエストも通常料金で課金されます。ここまでで挙動が世代・モデル群ごとに分かれる軸が複数出てきたため、次の早見表にまとめます。

Context awarenessのタグ注入と対応モデルは、1M/200kの系統分けと完全には一致しません(1M対応モデルの中にもOpus 4.7以降のように注入されないものがあります)。詳細は後段の「Context awareness」節で扱います。

コンテキストウィンドウに入るものと入らないもの

「コンテキストウィンドウ」はモデルがレスポンス生成時に参照できる全テキストを指し、モデルの学習データとは別物です。学習データは固定された巨大コーパスですが、コンテキストウィンドウは会話ごとの「作業メモリ」に相当します。ウィンドウが大きいほど複雑で長いプロンプトを扱えますが、トークン数が増えるほど精度や記憶の正確さが落ちる「コンテキスト腐敗(context rot)」という現象も知られています。ウィンドウに何を入れるかを取捨選択することは、単に容量を増やすことと同じくらい重要です。

リクエストに含まれるものはすべてコンテキストウィンドウにカウントされます。system prompt、messages内のすべてのメッセージ(tool result・画像・ドキュメントを含む)、tool定義がその対象です。生成されるテキスト応答(extended thinkingを含む)もカウントされます。各レスポンスのusageフィールドにはそのリクエストで消費した内訳が返り、プロンプトキャッシュを使っている場合はinput_tokens・cache_read_input_tokens・cache_creation_input_tokensの3つに分かれて計上されますが、3つともコンテキストウィンドウとしてはカウント対象である点は変わりません。

thinkingやtool useを併用するとカウント対象が増える

拡張思考(thinking)を有効にしている場合、thinkingトークンも入力・出力の両方でコンテキストウィンドウにカウントされます。thinkingトークンはmax_tokensのサブセットとして扱われ、出力トークンとして課金され、レートリミットにもカウントされます。前ターンのthinkingブロックを文脈に残すかどうかはモデルで既定挙動が異なり、Opus 4.5以降・Sonnet 4.6以降・Fable/Mythos系は既定で保持、それ以前のOpus・Sonnetと全Haikuモデルは会話履歴として渡し戻すと自動的に取り除かれます。tool useとthinkingを併用する場合、tool resultには対応するthinkingブロックを署名込みでそのまま返す必要があり、改変するとAPIがエラーを返します。

これらすべてがコンテキストウィンドウの消費に含まれるため、「入力オーバーフロー」と「生成中オーバーフロー」のどちらに当たるかを判断するときは、system prompt・messages・tool定義に加えてthinkingトークンの分もあらかじめ見積もりに含める必要があります。

モデルが自分の残量を把握する「Context awareness」

Claude Sonnet 5・Sonnet 4.6・Sonnet 4.5・Haiku 4.5にはContext awarenessという機能があり、会話全体を通じて自分の残りコンテキストウィンドウ(トークン予算)を追跡できます。これは自動で有効になり、呼び出し側が何かを設定したりタグを送ったりする必要はありません。APIが毎回のリクエストのsystem promptに現在の総コンテキストウィンドウ量を注入し、

<budget:token_budget>200000</budget:token_budget>

この値はそのリクエストで実際に使えるコンテキストウィンドウに一致します。上の例は200kモデルの場合で、Sonnet 5とSonnet 4.6では1Mに、Sonnet 4.5とHaiku 4.5では200kになります。固定値ではありません。

各tool call後には残量の更新も注入されます。

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

画像トークンもこの予算に含まれます。Opus 4.7以降のOpusモデル、Fable 5.1、Mythos 5.1、Fable 5、Mythos 5にはこのタグは注入されません。これらのモデルで同等の制御をしたい場合はベータ機能のtask budgetsで明示的な予算を渡します。Context awarenessは「オーバーフローが起きる前にモデル自身が使用量を意識してペース配分する」仕組みであり、model_context_window_exceededは「それでも上限に達してしまったときの事後的な通知」という位置づけの違いがあります。

コンテキストウィンドウ超過を避けるための恒常対策

一時しのぎではなく恒常的に対処する場合、次の2つの機能が使えます。

• サーバーサイドCompaction: 会話がしきい値に達すると自動で古い部分を要約し、コンテキストウィンドウの限界を先送りする。現状ベータ提供で、Claude 4.6以降のモデルとClaude Mythos Previewで使えます(発動しきい値の決め方はCompactionの発動しきい値の決め方を参照)
• Context editing: tool resultのクリアリングやthinking blockのクリアリングなど、より狙いを絞った文脈管理

いずれもプロンプトキャッシュされたプレフィックスに影響しますが、プロンプトキャッシュ自体はトークンが「コンテキストウィンドウを占有するかどうか」を変えるものではなく、「その分の支払い方」を変えるだけです。キャッシュされたトークンもコンテキストウィンドウには変わらずカウントされます。

オーバーフロー対策は入力側と生成側で実装を分ける

ここまでの挙動を実装に落とすと、対策すべき箇所は2つに分かれます。

入力オーバーフローは、リクエストを送る前にトークンカウンティングAPIで潰すのが唯一の確実な方法です。400エラーが返ってから対処するのではなく、送信前の見積もりを実装に組み込みます。生成中オーバーフローは、送信前には分からない以上、stop_reasonの分岐で受けるのが正しい設計です。model_context_window_exceededが返ってもレスポンス自体は有効なので、エラー扱いせずに途中結果として使う実装にします。

どちらの対策が必要かはモデル世代でも変わります。Sonnet 4.5より前のモデルを使っている場合、model_context_window_exceededを受け取るにはベータヘッダーでのopt-inが要ります。Context awarenessは、この2つの対策を代替するものではありません。モデルが残量を意識してペース配分する仕組みであって、上限そのものを引き上げるわけではないため、対応モデルでも入力オーバーフロー・生成中オーバーフローはどちらも普通に発生します。トークンカウンティングとstop_reason分岐は、Context awarenessの有無にかかわらず実装しておく必要があります。