Content Too Large
ActiveHTTP 413 Content Too Large indicates the server is refusing to process the request because the request content exceeds the size the server is willing or able to accept. Defined in RFC 9110 §15.5.14. Previously named 'Payload Too Large'. The server MAY close the connection or include Retry-After if the condition is temporary.
Description
The 413 Content Too Large status code indicates that the server is refusing to process a request because the request content is larger than the server is willing or able to process. The server MAY terminate the request, close the connection, or both.
This status was renamed from 'Payload Too Large' to 'Content Too Large' in RFC 9110 (June 2022) to align with the broader terminology shift away from 'payload' in HTTP semantics. The behavior and semantics remain identical — only the name changed. Servers and clients should treat both names as referring to the same status code.
If the condition is temporary — for example, the server's disk is full or a quota resets periodically — the server SHOULD generate a Retry-After header field to indicate when the client might retry. If the condition is permanent (a hard size limit configured by the administrator), no Retry-After is needed and the client should reduce the request size before retrying.
413 interacts closely with the 100 Continue mechanism. When a client sends Expect: 100-continue, the server can inspect Content-Length and reject with 413 BEFORE the client transmits the body — saving bandwidth on both sides. Without this mechanism, the client uploads the entire body only to be rejected after transmission completes.
Common server defaults reveal how pervasive size limits are: Nginx defaults to 1MB (client_max_body_size), Apache uses LimitRequestBody, Cloudflare's free tier caps at 100MB, and most API gateways enforce limits between 1MB and 10MB. These limits protect against denial-of-service via memory exhaustion, slow-loris-style attacks with massive bodies, and storage abuse.
Examples
POST /api/attachments HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=----FormBoundary
Content-Length: 52428800
Authorization: Bearer token123
------FormBoundary
Content-Disposition: form-data; name="file"; filename="presentation.pptx"
Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation
<50MB binary data>
------FormBoundary--HTTP/1.1 413 Content Too Large
Content-Type: application/json
Connection: close
{"error": "content_too_large", "message": "Request body exceeds maximum allowed size.", "max_size_bytes": 10485760, "received_bytes": 52428800, "documentation_url": "https://docs.example.com/limits#upload-size"}POST /api/bulk-import HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 15728640
Authorization: Bearer admin-token
{"records": [/* 100,000 records totaling 15MB */]}HTTP/1.1 413 Content Too Large
Content-Type: application/json
Retry-After: 3600
{"error": "content_too_large", "message": "Storage quota temporarily exceeded. Quota resets in 1 hour.", "max_size_bytes": 5242880, "quota_resets_at": "2024-03-15T14:00:00Z", "current_usage_bytes": 1073741824, "quota_limit_bytes": 1073741824}POST /api/uploads HTTP/1.1
Host: api.example.com
Content-Type: application/octet-stream
Content-Length: 536870912
Expect: 100-continue
Authorization: Bearer token123HTTP/1.1 413 Content Too Large
Content-Type: application/json
Connection: close
{"error": "content_too_large", "message": "Content-Length 536870912 exceeds maximum of 104857600 bytes. Upload rejected before body transmission.", "max_size_bytes": 104857600, "hint": "Use chunked upload API at /api/uploads/multipart for files over 100MB"}Edge Cases
- •413 can be returned BEFORE the body is sent when the client uses Expect: 100-continue and the server inspects Content-Length — this saves bandwidth but requires proper client-side handling of the rejection.
- •Nginx returns 413 with a default HTML error page unless custom error handling is configured. The response body is often useless to API clients — always configure custom JSON error responses for API routes.
- •Chunked transfer encoding (Transfer-Encoding: chunked) means the server may not know the total size upfront. Some servers accept the stream and abort mid-transfer, closing the connection without sending a proper 413 — the client sees a connection reset, not a status code.
- •Reverse proxies (Nginx, Cloudflare, AWS ALB) may return 413 before the request reaches your application server. The error format, headers, and limits are controlled by the proxy, not your app — ensure proxy and app limits are coordinated.
- •Some servers incorrectly return 413 for oversized headers (many cookies, long URLs). Technically, 431 Request Header Fields Too Large is the correct status for header-size violations. 413 is strictly for body/content size.
- •WebSocket upgrade requests with large initial frames can trigger 413 in servers that check payload size during the handshake phase — even though the WebSocket protocol has its own frame-size negotiation.
- •Email SMTP servers use a similar concept (552 message size exceeds maximum) but HTTP-based email APIs like SendGrid or Mailgun return 413 when attachment total size exceeds their per-request limit.
When You'll See This
- →User uploading a profile photo that exceeds the 5MB limit
- →API client sending a bulk import JSON body larger than the gateway allows
- →Email system rejecting an attachment that exceeds the per-message size limit
- →Mobile app attempting to upload a video file over a CDN's free-tier limit
- →CI/CD pipeline pushing a build artifact larger than the registry's max layer size
- →GraphQL mutation with an embedded base64 image exceeding the request body parser limit
- →IoT device firmware update payload exceeding the OTA server's per-request ceiling
Implementation References
| Language | Constant |
|---|---|
| Go | http.StatusRequestEntityTooLarge |
| Rust | http::StatusCode::PAYLOAD_TOO_LARGE |
| Python | http.HTTPStatus.REQUEST_ENTITY_TOO_LARGE |
| Node.js | http.STATUS_CODES[413] |
| .NET | HttpStatusCode.RequestEntityTooLarge |
| Java | HttpURLConnection.HTTP_ENTITY_TOO_LARGE |
| PHP | Response::HTTP_REQUEST_ENTITY_TOO_LARGE (Symfony) |
| Ruby | :request_entity_too_large (Rack) |
History
Introduced as '413 Request Entity Too Large' in HTTP/1.1 (RFC 2068, 1997). Renamed to '413 Payload Too Large' in RFC 7231 (2014) when 'entity' terminology was deprecated. Renamed again to '413 Content Too Large' in RFC 9110 (June 2022) as part of the comprehensive HTTP semantics revision that replaced 'payload' with 'content' throughout the specification.
Related Status Codes
Related Headers
FAQ
What is the difference between 413 Content Too Large and 431 Request Header Fields Too Large?
413 is for request BODY size violations — the content (JSON payload, file upload, form data) exceeds the server's configured maximum. 431 is for request HEADER size violations — too many cookies, an excessively long Authorization token, or too many custom headers. Some servers incorrectly return 413 for header issues, but RFC 6585 introduced 431 specifically to distinguish the two cases. Check whether the size limit applies to Content-Length (413) or total header size (431).
How should clients handle 413 and implement retry logic?
First, check for a Retry-After header — if present, the condition is temporary (quota reset, disk full) and the client should wait and retry unchanged. If no Retry-After is present, the limit is permanent and the client must reduce the request size. Strategies include: compressing the body (Content-Encoding: gzip), splitting into multiple smaller requests, using chunked/multipart upload APIs, or reducing the dataset. Always read the response body for max_size_bytes or documentation links that specify the exact limit.
Why do I get 413 from Nginx even though my app allows larger uploads?
Nginx enforces client_max_body_size (default: 1MB) BEFORE proxying to your application. The request never reaches your app server. Fix by setting 'client_max_body_size 50m;' in the appropriate server/location block. Similarly, if you're behind Cloudflare, AWS ALB, or another reverse proxy, each layer has its own size limit that is evaluated independently. The effective limit is the MINIMUM across all layers in the request path.