Claude API 413 request_too_large: Causes and Fixes

Your call to /v1/messages fails with HTTP 413 request_too_large. This error is about the raw size of the HTTP body in bytes — not tokens, not the model, not your key. Here is where the limits sit, why image- and PDF-heavy requests hit them, and how to get the work through.

Quick answer

A 413 request_too_large means the request body has more bytes than the endpoint accepts. On Anthropic's first-party API the Messages endpoint allows 128 MB per request (Batch 256 MB, Files API 500 MB); cloud platforms are lower — 20 MB on Amazon Bedrock, 30 MB on Google-managed Google Cloud, 32 MB on Claude Platform on AWS. The usual culprit is base64-encoded images or PDFs, often resent on every turn of a conversation. Downscale media, upload large files once with the Files API and reference them by file_id, and split big jobs. Retrying unchanged will fail the same way.

Symptoms and What the Error Means

Anthropic documents the error type and status code; the message text below is how it appears in public bug reports:

{
  "type": "error",
  "error": {
    "type": "request_too_large",
    "message": "Request exceeds the maximum size"
  }
}

Per Anthropic's errors page, on the first-party API this response comes from Cloudflare, before the request reaches the API servers — nothing was parsed, tokenized or sent to a model. If a reverse proxy of your own sits in front, you may instead get its HTML error page (for nginx, 413 Request Entity Too Large) with no JSON at all.

Don't confuse it with:

• 400 "prompt is too long" — too many tokens for the context window. A body full of images can be too many bytes while well under the token limit, and the reverse. See prompt is too long.
• Errors about individual images — separate per-image checks on size and dimensions, covered below.

The Limits That Apply

From Anthropic's API overview and errors pages:

Endpoint (first-party Claude API)	Maximum request size
Messages API	128 MB
Token Counting API	128 MB
Message Batches API	256 MB
Files API (per upload)	500 MB

Other platforms set their own limits: Amazon Bedrock 20 MB, Claude Models on Google Cloud (Google managed) 30 MB, and 32 MB for Messages and Token Counting on Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry. You will also see "32 MB" quoted for Claude in older articles; the current first-party figure is 128 MB. The effective ceiling is the smallest limit anywhere on the path, including your own proxies.

Separate per-image rules from Anthropic's vision docs:

• Up to 10 MB per image (base64-encoded) on the Claude API; 5 MB on Bedrock.
• Maximum dimensions 8000×8000 px. If a request carries more than 20 images, a stricter per-image dimension limit applies; Anthropic suggests keeping both sides at or under 3,000 px, or the request at 20 or fewer image and document blocks.
• Up to 600 images or PDF pages per request (100 on 200K-context models). Anthropic warns you may hit the request size limit before reaching 600.

Why It Happens

1. Base64 overhead. Base64 turns every 3 bytes into 4 characters, so a 9 MB PDF becomes about 12 MB of JSON.
2. History resends. Each request carries the full conversation; as Anthropic's vision guide notes, base64 images ride along on every turn. A chat with a few screenshots grows until it crosses the line — usually mid-session.
3. Agent screenshots. Computer-use and browser agents return an image in a tool_result at each step.
4. Full-resolution originals. Phone photos and retina screenshots go out at full size, though Claude downscales images above its native resolution anyway.
5. A smaller hop in the middle. nginx's default client_max_body_size is 1 MB; serverless platforms and API gateways have their own payload caps.

Fix 1: Measure the Payload

Check the size of the exact bytes you send — not the file on disk:

import json

body = {"model": "claude-sonnet-5-5", "max_tokens": 1024, "messages": messages}
size_mb = len(json.dumps(body).encode("utf-8")) / 1_000_000
print(f"request body: {size_mb:.1f} MB")
if size_mb > 100:   # keep a margin below the 128 MB first-party cap
    raise ValueError("request too large: downscale, use file_id, or split")

Run this right before the API call in your agent loop. If size climbs turn after turn, the cause is history (Fix 4), not a single large file.

Fix 2: Downscale and Compress Images Before Encoding

Sending a 12-megapixel photo buys nothing if the model will downscale it anyway, and it costs bytes on every turn. Resize first:

import base64, io
from PIL import Image

def encode_image(path, max_side=2000, quality=85):
    img = Image.open(path)
    img.thumbnail((max_side, max_side))          # keeps aspect ratio
    buf = io.BytesIO()
    img.convert("RGB").save(buf, format="JPEG", quality=quality)
    return base64.standard_b64encode(buf.getvalue()).decode()

max_side=2000 and JPEG quality 85 are starting points, not official values; check Anthropic's vision page for the native resolution of the model you use, and keep sides at 3,000 px or below if a request carries more than 20 images. Keep PNG for screenshots with small text if JPEG artifacts hurt legibility. For computer-use and browser-use agents, resizing is mandatory: Anthropic rejects an oversized screenshot in a tool_result with a validation error instead of downscaling it.

Fix 3: Upload Once with the Files API

The Files API is built for this. You upload a file once, get a file_id, and reference it in Messages requests instead of embedding base64. It is out of beta and needs no beta header, each file can be up to 500 MB, and the file operations themselves are free (file content used in a request is billed as input tokens).

# 1. Upload
curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@report.pdf"
# => {"id": "file_011CNha8iCJcU1wXNR6q4V8w", ...}

# 2. Reference it
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-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": [
      {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}},
      {"type": "text", "text": "Summarize the key findings."}
    ]}]
  }'

Things to know before relying on it:

• Availability. Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry (hosted on Anthropic). Bedrock and Claude Models on Google Cloud (Google managed) accept only base64 image and PDF sources.
• Scope. Files belong to the workspace that uploaded them, and any key in that workspace can read them. Never accept file_id values from end users.
• It doesn't shrink tokens. The content still counts toward the context window, so a huge text file can still fail with "prompt is too long".

Images and PDFs can also be referenced with a url source, so Anthropic fetches them instead of you embedding the bytes.

Fix 4: Stop Resending Stale Media and Split Big Jobs

• Prune history. Once Claude has described a screenshot, replace that old image block in your stored history with a short text note. Never remove a tool_result block itself, or you will trigger tool_use without tool_result — just swap its image content for text.
• Split PDFs. Process a long document in page ranges and merge the answers.
• Check your own hops. Raise client_max_body_size in nginx, and check payload caps on serverless platforms and API gateways in between.

A 413 is deterministic: the same body fails every time, so retry only after changing the payload. If an agent framework keeps resending the same oversized history, start a new session or remove the attachment from history.

If You're Calling Claude Through byesu

byesu is an AI API gateway with an OpenAI-compatible endpoint (https://byesu.com/v1) and an Anthropic-native endpoint (/v1/messages on the same host), billed pay-as-you-go with no subscription. Two points matter here:

• A file_id is not portable. Files are scoped to the Anthropic workspace that uploaded them, so an ID from your own Anthropic account means nothing to any other service. Through byesu, keep requests lean with downscaled base64 media (Fix 2) and pruned history (Fix 4).
• The same arithmetic applies on both endpoints. On /v1/chat/completions, an image_url with a data: URI is base64 too, so the 4/3 overhead and the resend-every-turn growth still apply. Measure the body with the snippet in Fix 1 whichever format you use.

To get started, create a token in the console, point your SDK at the endpoint above, and use a model ID such as claude-sonnet-5-5. Full setup: Quick Start.

FAQ

What does the Claude API 413 request_too_large error mean?

It means the HTTP request body has more bytes than the endpoint accepts. It is a size check on the raw payload, not a token or context-window check, and on Anthropic's first-party API it is returned by Cloudflare before the request reaches the API servers. The same body fails every time, so you have to make the request smaller before retrying.

What is the maximum request size for the Claude API?

On Anthropic's first-party API, Messages and Token Counting requests can be up to 128 MB, Message Batches requests up to 256 MB, and Files API uploads up to 500 MB per file. Other platforms are lower: Amazon Bedrock 20 MB, Claude Models on Google Cloud (Google managed) 30 MB, and 32 MB for Messages on Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed) and Microsoft Foundry.

Is 413 request_too_large the same as "prompt is too long"?

No. 413 request_too_large is about bytes in the HTTP body, usually from base64 images or PDFs. "prompt is too long" is a 400 about tokens exceeding the model's context window. A request can fail either check independently, and the fixes differ: shrink or upload media for a 413, and trim or summarize content for "prompt is too long".

How do I send large images or PDFs to Claude without a 413?

Downscale and compress images before base64-encoding them, and upload large files once with the Files API, then reference them with a file_id in a document or image block. Also remove old base64 media from conversation history, since every request resends the full history, and split very long PDFs into page ranges.

Should I retry a 413 error?

Not unchanged. A 413 is deterministic, so the same payload fails every time and blind retries only waste time. Measure the body size, shrink or move the media, then send again. If the error comes from your own proxy (for example nginx's default client_max_body_size of 1 MB), raise that limit instead.