Claude APIのリクエストサイズ上限と413エラーの見分け方

Claude APIのリクエストサイズ上限は、1つの数値ではなくエンドポイントごとに違います。Messages APIとToken Counting APIは32MB、Message Batches APIは256MB、Files APIは500MBです。上限を超えると413のrequest_too_largeエラーが返り、直接APIを使っている場合はAnthropicのサーバーに届く前にCloudflareがこのエラーを返しています。

この記事では、エンドポイント別の上限表、Cloudflareが処理を止める仕組み、パートナー運用プラットフォーム(Bedrock・Google Cloud)での上限の違い、そして413に遭遇したときの回避策を扱います。

エンドポイント別のリクエストサイズ上限

Claude APIが直接運用するエンドポイントの上限は次のとおりです。

Messages APIとToken Counting APIが同じ32MBという点は覚えておく価値があります。トークン数を事前に見積もるためにToken Counting APIへ投げたペイロードがサイズ超過でエラーになるなら、そのままMessages APIへ送っても同じ理由で失敗します。事前チェックとして機能する組み合わせです。

Managed Agentsの/v1/agents・/v1/sessions・/v1/environmentsも同じ32MBの枠に入ります。エージェント定義や会話履歴を大量に積んだセッションのシード処理では、この上限を意識する必要があります。

413エラーはどこで発生しているか

413 request_too_largeは、リクエストが許容バイト数を超えたときに返るエラーです。ここで重要なのは、エラーがどこで発生したかです。

直接Claude APIを使う実装では、この413はリクエストがAnthropicのAPIサーバーに到達する前に、手前のCloudflareが返しています。つまり413が返った時点で、リクエストの内容はAnthropic側では一切処理されていません。認証エラーやレート制限のように「Anthropicのシステムまで届いたが弾かれた」のではなく、その手前で止まっている点が他のエラーコードと違います。

エラー本体はJSON形式で返ります。

{
  "type": "error",
  "error": {
    "type": "request_too_large",
    "message": "..."
  },
  "request_id": "req_..."
}

他のエラーコード全般の分類とリトライ設計は、Claude APIのエラーハンドリング設計で扱っています。413はその中でも「送信前に自分のコードでチェックできる」数少ない種類のエラーです。

なぜエンドポイントごとに上限が違うのか

上限の差は、各エンドポイントが本来扱うデータの性質に対応しています。Messages APIとToken Counting APIは、1回の会話ターンに含まれるテキストや画像を送るためのエンドポイントで、通常の用途では32MBを超えることはまれです。Message Batches APIは、この32MBのリクエストを大量に束ねて一括投入するためのエンドポイントなので、上限も256MBと1桁大きく設定されています。Files APIはPDFや動画など、そもそも1ファイルが数百MBに達し得るバイナリを扱うためのエンドポイントで、500MBという上限はその用途に合わせた数字です。

つまり、32MBという数字を「小さすぎる」と感じたときの正しい対処は、上限を引き上げる方法を探すことではなく、そのデータをより適切なエンドポイントに逃がすことです。大きなファイルはFiles APIへ、大量のリクエストはBatch APIへというのは、上限の作られ方そのものに沿った設計になります。

パートナー運用プラットフォームでは上限が別に存在する

Anthropicが直接運用するClaude API・Claude Platform on AWSでは、上の表の上限がそのまま適用されます。一方、パートナーが運用するプラットフォームには、それぞれ独自のリクエストサイズ上限があります。

Bedrock経由でのリクエストは、直接APIのMessages API上限(32MB)より小さい20MBで制限されます。同じモデル・同じSDKコードでも、Bedrock経由に切り替えた途端に413が出るようになるケースは、この差が原因であることが多いです。Google Cloud経由も同様に30MBとやや小さめです。パートナープラットフォームの上限は各社のドキュメントで随時更新されるため、正確な最新値は利用中のプラットフォームの公式ドキュメントで確認する必要があります。

この違いが実務で厄介なのは、多くのSDKが「エンドポイントの向き先(base_url)を変えるだけ」で直接APIとBedrock・Google Cloudを切り替えられるように作られている点です。コード上はモデル名とAPIキーの設定を差し替えただけのつもりでも、リクエストサイズの上限は環境ごとに別物になります。ステージング環境で直接APIを使い、本番環境ではガバナンス上の理由でBedrock経由に切り替えている構成では、ステージングで通っていたペイロードが本番でだけ413になるという事象が起きやすくなります。動作確認は最終的にリクエストを送る先のプラットフォームで行い、上限値もそのプラットフォームの数字を基準に設計するのが安全です。

413を避けるための実践的な対処

413は送信前に自分のコードでチェックできる数少ないエラーです。リクエストボディを組み立てた直後、送信する前にバイト数を測っておけば、上限超過を413として受け取る前に検知できます。Node.jsでは次のように書けます。

const payload = JSON.stringify(requestBody);
const sizeInBytes = Buffer.byteLength(payload, "utf8");
const MESSAGES_API_LIMIT = 32 * 1024 * 1024; // 32MB
 
if (sizeInBytes > MESSAGES_API_LIMIT) {
  throw new Error(
    `リクエストサイズが上限超過: ${sizeInBytes}バイト (上限 ${MESSAGES_API_LIMIT}バイト)。Files APIへの切り替えを検討してください。`
  );
}

Pythonでも同じ考え方で、len(payload.encode("utf-8"))でバイト数を取得し、エンドポイントごとの上限(32MB / 256MB / 500MB)と比較するだけです。この事前チェックを送信直前のミドルウェアや共通関数に1つ置いておけば、413そのものを未然に防げます。使っているエンドポイントがMessages APIなのかBatch APIなのかによって基準値が変わる点だけ、関数の呼び出し側で意識しておく必要があります。

画像やPDFをBase64でリクエストボディに埋め込む実装では、この事前チェックが特に効きます。Base64エンコードは3バイトの元データを4文字に変換するため、元ファイルよりおよそ1.33倍(約33%)サイズが膨らみます。たとえば24MBのPDFをBase64化すると約32MBになり、Messages APIの上限をちょうど超える計算になります。「ファイルサイズは上限未満のはずなのに413が出る」というケースの多くは、このBase64膨張分を見落としています。

まとめ

Claude APIのリクエストサイズ上限は一律ではなく、Messages API・Token Counting APIが32MB、Message Batches APIが256MB、Files APIが500MBとエンドポイントごとに決まっています。413エラーは直接APIではCloudflareが手前で返すため、Anthropic側の処理には一切入っていません。公式ドキュメントがリトライを明記しているのは500・504・529のみで、413は含まれていない点も、413をリトライ設計にどう組み込むかを考えるうえで見落としやすいポイントです。Bedrock(20MB)やGoogle Cloud(30MB)経由では、直接APIより小さい独自の上限が別に存在することも合わせて把握しておく必要があります。

送信前にリクエストボディのバイト数を計測し、Base64化による約1.33倍の膨張分を見込んでおけば、413が返ってくる前に自分のコード側で気づけます。大きなファイルはFiles API、大量のリクエストはBatch APIに逃がすことで、413そのものを避けた設計にできます。