Anthropic request_too_large: meaning, cause, and fix

Bytes, not tokens

Token limits and byte limits are separate. A context-window error concerns the model's token budget. A 413 concerns the raw request body and can be rejected before model processing begins. Anthropic documents a 32 MB limit for the Messages API.

A request can fit the context window and still exceed the byte limit. Attachments are the common cause. Binary content encoded as base64 adds roughly one third to its size, so images combined with a long message history can hit the body limit before the token limit.

Request limits by endpoint

Anthropic request-size caps by endpoint, per the API error docs

Endpoint	Max request size
Messages API	32 MB
Token Counting API	32 MB
Batch API	256 MB
Files API	500 MB

Note the first two rows match: the Token Counting API shares the Messages cap, so an oversized payload can't even be size-checked by sending it there. It bounces at the same wall, which means the counting has to happen on your side of the wire.

The error response

{
  "type": "error",
  "error": {
    "type": "request_too_large",
    "message": "Request exceeds the maximum allowed number of bytes."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Same envelope as every Anthropic error: branch on the type field, and in SDK code catch the typed exception class for the status rather than string-matching the message. Responses carry a req_-prefixed request-id header that the SDKs expose; quote it if the failure turns into a support thread.

Shrink or relocate

The fix starts with a measurement the SDK won't do for you, since the client libraries send whatever you hand them. One function in your wrapper settles it:

# Python: measure the body before the edge does
import json

CAP_MB = 32  # Messages API ceiling, in bytes rather than tokens

def body_size_mb(payload: dict) -> float:
    return len(json.dumps(payload).encode("utf-8")) / 1_048_576

size = body_size_mb(payload)
if size >= CAP_MB:
    # usual culprit: base64 images inline in content blocks
    reroute(payload)  # assets to the Files API, bulk to Batch

If the serialized payload is large, inspect embedded media first. Anthropic's Files API accepts files up to its documented 500 MB cap, allowing an asset to be uploaded once and referenced from a message rather than embedded in each request.

Eligible bulk jobs can use the Batch API, which accepts 256 MB per request and is listed at a 50% discount to standard Claude pricing. Anthropic's documentation also directs long-running work, especially jobs beyond 10 minutes, toward streaming or the Batch API instead of one large synchronous call.

If your failure is token-shaped instead of byte-shaped, that's a different page: the request fit down the wire but overflowed the model's window. The context_length_exceeded breakdown covers the token-side playbook, and the context-window comparison shows which models give you room to stop trimming.