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

入力が超えるか、生成中に超えるかで応答が分かれる

Claude APIでコンテキストウィンドウの上限に当たったとき、応答は2通りに分かれます。入力の時点で超えていれば、どのモデルでも400エラーで弾かれます。入力は収まっていて生成中に超えた場合は、後発のモデルに限り、途中までの結果がstop_reason: "model_context_window_exceeded"で返ります。

片方の対処だけを実装すると、もう片方を取りこぼします。400は例外として捕まえる経路、model_context_window_exceededは成功レスポンスのstop_reasonとして分岐する経路です。例外処理だけを書いていると、後者はそもそも例外にならないので素通りします。

コンテキストウィンドウがいっぱいになったときの症状と原因

「context window full」に当たったとき、手元に見えるものから原因を引けます。

400の文言はAPIが返すものです。ログに別の表現で出ている場合は、SDKや連携ツールが包み直している可能性があるため、元のレスポンスのステータスとstop_reasonを見て表の行を選びます。

入力オーバーフローは送る前に見積もる

400は送信してから初めて分かるので、大きな入力を扱う実装では送信前にcount_tokensエンドポイントで見積もります。トークンカウンティングAPIは無料ですが、利用ティアごとの毎分リクエスト数の制限は受けます。返るのは見積もりで、実際のメッセージ作成時のトークン数と少し食い違うことがあります。システムが自動で足したトークンが含まれることがありますが、課金対象にはなりません。上限は利用ティアごとに毎分リクエスト数で決まり、Startが5,000、Buildが10,000、Scaleが20,000です。メッセージ作成とは別枠なので、片方を使ってももう片方の上限は減りません。

実装で押さえておく点が4つあります。

• cache_controlブロックを付けてもカウント時にはキャッシュが効かない。キャッシュが効くのは実際のメッセージ作成時だけ
• 数えるときは、実際に使うmodelのIDを指定する。Opus 4.7より前のモデルで数えた値は、新しいトークナイザーのモデルの見積もりには流用できない。同じ入力でも、Claude 4.7以降のモデルとMythos Previewは、それ以前のモデルより約30%多くトークンが出る。増え方は内容次第なので、今のモデルと移行先で同じリクエストを2回数え、input_tokensを比べる
• 画像や大きなドキュメントを送る場合、トークンより先にリクエストサイズに当たることがある。上限はMessages APIとToken Counting APIが32MB、Batch APIが256MB。超えると400ではなく413のrequest_too_largeになる
• 413は、直接のClaude APIではCloudflareがAPIサーバーに届く前に返す。モデルまで届かないので、トークン上限の判定とは別の経路になる

エンドポイントはmessagesと同じ構造の入力(system prompt・tool定義・画像・PDFを含む)を受け取り、入力トークンの合計を返します。誤差があるので、上限ぎりぎりの値で送るかどうかを決める使い方には向きません。余白を残して判定します。

count_tokensは、Messages APIが受け付ける入力の一部をinvalid_request_errorで拒否します。

対象は、web searchやweb fetchなどのサーバーツール(advisorツールを除く)、MCPコネクタ、urlやfileをソースにしたimage・documentブロックです。画像とPDFはbase64で送れば数えられます。

生成中に超えたときはモデル世代で挙動が変わる

入力は上限内でも、max_tokensまで出力させると超える場合の挙動は世代で分かれます。

公式の2ページで、新しい挙動の対象範囲の書き方が違います。コンテキストウィンドウのページは「Claude 4.5モデル以降」、stop reasonのページは「Sonnet 4.5以降のモデルはベータヘッダー不要」としています。この挙動はSonnet 4.5の公開と同じ2025年9月29日に導入されました。Haiku 4.5(同年10月15日)とOpus 4.5(同年11月24日)はそれより後の公開で、どちらの書き方でも新しい挙動の側に入ります。

この値はSDKのbeta名前空間にだけ型定義があります。ベータヘッダーなしで返ってくる対象のモデルでも、コード側は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-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-5",
    max_tokens=20000,
    messages=[{"role": "user", "content": "..."}],
)
 
if response.stop_reason == "model_context_window_exceeded":
    # レスポンスは有効だが、max_tokensに届く前にウィンドウで打ち切られた
    print("context window limit reached")

公式のstop reason一覧では、この値への推奨対応は「レスポンスを途中で切れたものとして扱う」です。例外ではなく、max_tokensで止まったときと同じ種類の切り詰めとして受けます。ウィンドウが埋まった状態なので、同じ会話にそのまま続きを求めても余地がありません。続けるなら、「上限に近づく会話を続ける手段」の節にあるCompactionやContext editingで空きを作ってからにします。

Pythonの公式例には、max_tokensを約21k超にするとSDKがストリーミングを要求するという注記があります。上の20000はこの範囲に収まる値です。出力上限の128kまで狙うような呼び出しでは、この注記が当てはまるかを先に確認します。

入力サイズ不明でも最大出力を取る使い方

model_context_window_exceededはエラー通知にとどまらず、入力サイズを計算せずに取れるだけ出力させる実装を可能にします。max_tokensを大きめに指定すれば、実際にどこまで出るかはウィンドウの残量が決めるので、送信前のトークン見積もりを省けます。

コード例は入力サイズ不明でも最大出力を引き出すmodel_context_window_exceeded活用法にあります。

モデルごとのウィンドウサイズと関連する上限

1Mトークンのウィンドウを持つのは、次のモデルです。

• Fable 5.1・Mythos 5.1・Fable 5・Mythos 5
• Opus 5.5・5・4.8・4.7・4.6
• Sonnet 5.5・5・4.6、Haiku 5.5、Mythos Preview

Sonnet 4.5を含むそれ以外のモデルは200kトークンです。1Mのモデルでは1Mが既定で、ベータヘッダーは不要です。長文コンテキストも通常料金で課金されます。例外はHaiku 5.5で、100,000トークンを超えるプロンプトは割高になります。1Mの実務での使い方はClaude 1Mコンテキストの実務活用にあります。

後述するContext awarenessの残量タグの有無は、1Mか200kかという分け方とは一致しません。同じ1Mのモデルでも、Sonnet 5には入りSonnet 5.5には入りません。

ウィンドウに数えられるもの

コンテキストウィンドウは、モデルが応答の生成時に参照できる全テキストを指します。学習データとは別物で、会話ごとの作業メモリにあたります。大きいほど長いプロンプトを扱えますが、トークンが増えるほど情報の取りこぼしが増える現象はcontext rot(コンテキスト腐敗)と呼ばれます。何を入れるかを選ぶことは、容量を増やすことと同じくらい重要です。

数えられるのは、system prompt、messages内のすべてのメッセージ(tool result・画像・ドキュメントを含む)、tool定義です。モデルが生成する応答も、extended thinkingを含めて数えられます。各レスポンスのusageには消費の内訳が入ります。プロンプトキャッシュを使うと、入力は次の3つに分かれて返ります。input_tokens・cache_read_input_tokens・cache_creation_input_tokensで、3つともウィンドウの対象です。キャッシュは支払いを変えるだけで、トークンが占める場所は変わりません。

thinkingを併用するとカウントが増える

thinkingトークンは入力側と出力側のどちらでもウィンドウに数えられます。max_tokensの一部として扱われ、出力トークンとして課金され、レートリミットにも数えられます。

前ターンのthinkingブロックを残すかどうかはモデルで違います。Opus 4.5以降・Sonnet 4.6以降・Haiku 5.5・Fable/Mythos系は既定で保持するので、ターンを重ねるほど入力が膨らみます。それ以前のOpus・Sonnetと、Haiku 4.5までの全Haikuモデルは、履歴として返すとAPIが自動で取り除きます。tool useと併用するときは、tool resultと一緒に対応するthinkingブロックを署名込みで返します。改変するとエラーになります。

見積もりの段階では、この保持の違いが効きます。保持するモデルで長い会話を続けるなら、過去のthinking分も入力側に積み上がるものとしてcount_tokensの対象に含めます。

モデルが残量を把握するContext awareness

Claude Sonnet 5・Sonnet 4.6・Sonnet 4.5・Haiku 4.5は、会話を通じて残りのトークン予算を追跡します。自動で有効になり、呼び出し側が設定やタグの送信をする必要はありません。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、Sonnet 5.5、Haiku 5.5、Fable 5.1、Mythos 5.1、Fable 5、Mythos 5にはタグが入りません。同等の制御をしたいときは、ベータ機能のtask budgetsで明示的な予算を渡します。

Context awarenessは、モデルが使用量を意識してペースを配分する仕組みです。上限そのものは変わらないので、対応モデルでも入力オーバーフローと生成中のオーバーフローはどちらも起きます。model_context_window_exceededは、配分しても届いてしまったときの事後の通知にあたります。

上限に近づく会話を続ける手段

会話が長くなる用途では、次の2つが使えます。

• サーバーサイドCompaction: しきい値に達すると古い部分を自動で要約する。ベータ提供で、Claude 4.6以降のモデルとMythos Previewが対象。発動しきい値の決め方はCompactionの発動しきい値の決め方を参照
• Context editing: tool resultのクリアやthinkingブロックのクリアなど、対象を絞った文脈の管理

実装は入力側と生成側で分ける