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がこのエラーを返します。

この記事では、エンドポイント別の上限と、413が出たときの切り分け、パートナー運用プラットフォーム(Bedrock・Google Cloud)での上限の違い、サイズ以外の理由で同じように失敗するPDF・画像の制限、送信前のチェック方法を扱います。

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

APIの概要ページのリクエストサイズ表には、Messages・Token Countingのほか、Sessions・Agents・Environmentsの行があります。エラーページの同じ趣旨の表にはこの行がなく、Messages API、Token Counting API、Batch API、Files APIの4行です。Managed Agentsの/v1/agents・/v1/sessions・/v1/environmentsが32MBの枠に入るのは概要ページの記載です。

Messages APIとToken Counting APIが同じ32MBという点は、事前チェックに使えます。トークン数を見積もるためにToken Counting APIへ投げたペイロードがサイズ超過になるなら、同じ内容をMessages APIへ送っても同じ理由で失敗します。

Message Batches APIには、サイズとは別にリクエスト数の制約もあります。1つのバッチは10万件のMessageリクエストか256MBの、先に達したほうが上限です。小さなリクエストを大量に束ねる場合は件数が、大きなペイロードを少数束ねる場合はサイズが先に効きます。

Files APIの500MBは、1回のアップロードで送るファイル1つの上限です。組織全体の保存容量は1TBで、超えると400エラーになります。Files API関連の呼び出しは、おおむね毎分500リクエストまでです。500MB超のファイルの413は、Files APIのエラー一覧に「File too large」として別に載っています。

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

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

直接Claude APIを使う実装では、この413はリクエストがAPIサーバーに到達する前に、手前のCloudflareが返します。413が返った時点で、リクエストの内容はAnthropic側のAPIでは処理されていません。

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

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

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

413ではなく別のエラーになるサイズ起因の失敗

32MBを超えていなくても、サイズや量が原因で失敗するケースがあります。エラーの種類で原因が分かれるので、どれに当たったかを先に見ます。

PDFにも、バイト数とは別の制限があります。リクエストの上限は32MBで、ページ数は1リクエスト600ページです。コンテキストウィンドウが100万トークン未満のリクエストでは100ページになります。どちらの制限も、PDFと一緒に送るほかの内容を含めたリクエスト全体にかかります。

密度の高いPDF(小さな文字が詰まったページ、複雑な表、重いグラフィック)は、ページ数の上限に達する前にコンテキストウィンドウが埋まることがあります。Files APIを使っていても、大きなPDFを含むリクエストはページ数の上限より先に失敗することがあります。対処としては、文書を分割するか、各ページが画像として処理されるため、埋め込み画像を縮小します。

画像は1リクエストに最大600枚(コンテキストウィンドウが20万トークンのモデルでは100枚)で、1枚あたりの最大寸法は8000×8000pxです。さらに、1リクエストに21枚以上の画像が含まれると、すべての画像に、より厳しい寸法制限がかかります。過去のターンから再送する画像や、tool_resultの中の画像(computer useのスクリーンショットなど)も数に入ります。

超えた場合は、エラーメッセージに「many-image requests」とその時点の上限ピクセル数が含まれるinvalid_request_errorで拒否されます。回避するには、各画像の縦横を2000px以下に縮めるか、1リクエストの画像を20枚以下にします。

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

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

直接APIのMessages APIの上限は32MBで、表のとおりBedrockとGoogle Cloudはそれより小さい値です。同じモデル・同じSDKコードでも、Bedrock経由へ切り替えた途端に、直接APIで通っていたペイロードが上限を超えます。パートナープラットフォームの値は各社のドキュメントで更新されるので、最新値は利用中のプラットフォームで調べます。

BedrockとGoogle Cloudでは、画像の枚数を数える方法も違います。21枚以上で寸法制限が厳しくなる上の判定には、この2つの面ではPDFなどのdocumentブロックも数えられます。PDFを何件も添付する構成は、直接APIでは通る枚数でも、パートナー経由では寸法制限に触れることがあります。

モデル名と認証を差し替えても、リクエストサイズの上限は環境ごとに別物です。ステージングで直接APIを使い、本番でBedrock経由にしている構成では、ステージングで通ったペイロードが本番でだけ上限超過で失敗し得ます。動作確認は最終的に送信する先のプラットフォームで行い、上限もその数字を基準にします。

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では、エンドポイントごとの上限を辞書に持たせると、呼び出し側で基準値を意識せずに済みます。

import json
 
LIMITS = {
    "messages": 32 * 1024 * 1024,
    "batches": 256 * 1024 * 1024,
    "files": 500 * 1024 * 1024,
}
 
def check_size(endpoint: str, body: dict) -> int:
    size = len(json.dumps(body).encode("utf-8"))
    if size > LIMITS[endpoint]:
        raise ValueError(f"{endpoint}の上限超過: {size}バイト")
    return size

BedrockやGoogle Cloudへ送るなら、LIMITSの値をそれぞれ20MB・30MBにします。

画像やPDFをBase64でリクエストボディに埋め込む実装では、この事前チェックが特に効きます。Base64は3バイトの元データを4文字に変換するため、元ファイルより約1.33倍(約33%)膨らみます。25MBのPDFをBase64化すると約33.3MBになり、Messages APIの32MBを超えます。ファイルサイズが上限未満でも413になる場合は、この膨張分を見落としている可能性があります。

上限との関係は、元ファイルのサイズから逆算できます。24MBのPDFはBase64化で約32MBとなり、テキストなど同じリクエストの他の内容を足せば32MBに収まりません。Messages APIに載せられる元ファイルの目安は、他の内容を除いて24MB弱です。

Bedrock経由では、同じ計算の天井が20MBに下がります。16MBのPDFは、直接APIならBase64化後の約21.3MBで通りますが、Bedrockでは20MBを超えます。元ファイルで15MB前後が、Bedrockに載せられるおおよその上限です。

エラー本体のrequest_idは、サポートへ問い合わせるときに添える識別子です。送信したサイズと送信先のエンドポイントも手元のログに残しておくと、原因の切り分けに使えます。

まとめ

32MBを超える見込みのデータは、上限の引き上げ先を探すのではなく、Files APIのように、より大きい上限を持つエンドポイントへ回します。パートナー経由で動かす場合は、上限が20MBや30MBまで下がる前提で、本番の送信先で確かめます。