An HTTP 413 Payload Too Large response indicates that the server is refusing to process a request because the request payload is larger than the server is willing or able to process.

HTTP 413 at a glance

  • Status: 413
  • Phrase: Payload Too Large (formerly Request Entity Too Large in RFC 2616)
  • Class: 4xx Client Error
  • Specification: RFC 9110 Section 15.5.14
  • Optional header: Retry-After (if the condition is temporary)
  • Connection policy: The server may close the connection (Connection: close) to prevent reading remaining body data
  • Client retry: Unsafe without reducing payload size or switching to direct upload mechanisms

What a 413 response tells you

When a client receives an HTTP 413 status code, specific protocol facts are established:

  1. The payload size exceeded a configured limit: The size of the request body (measured via Content-Length or chunked transfer stream) surpassed the threshold permitted by the receiving server or an intermediary.
  2. The server terminated request processing: To conserve memory, disk buffers, and network bandwidth, the server refused to process the body further.
  3. The condition may be permanent or temporary: If the condition is temporary (e.g., temporary server load or storage constraints), the server may include a Retry-After header.

What a 413 does not tell you

While an HTTP 413 confirms that the payload size exceeded limits, it does not reveal:

Client -> [Reverse Proxy (Limit A)] -> [API Gateway (Limit B)] -> [Application Middleware (Limit C)]

Receiving an HTTP 413 does not immediately prove:

  • Which specific layer enforced the limit (reverse proxy, CDN, gateway, or application).
  • Whether the payload syntax or formatting is valid.
  • Whether the user has permission to perform the action.

Similar status codes

400 Bad Request

The request contains malformed syntax or unparseable framing, regardless of size.

415 Unsupported Media Type

The payload format (Content-Type) is not supported by the endpoint, even if the payload size is small.

422 Unprocessable Content

The payload format and size are acceptable, but semantic validation rules failed.

For related diagnostics, consult our guides on HTTP 400 Bad Request and HTTP 415 Unsupported Media Type.

Diagnostic scenarios

Two primary scenarios cause HTTP 413 responses in web services:

Scenario 1: Reverse proxy upload buffer cutoff

An application provides a document or image upload endpoint. By default, NGINX limits request bodies to 1 MB (client_max_body_size 1m;). When a user submits a 10 MB file through a web form, NGINX intercepts the request before passing it to the application upstream and returns a 413 status code with Connection: close.

Scenario 2: Batch mutation exceeding framework memory limits

An API client attempts to synchronize 10,000 product records by sending a 5 MB JSON payload in a single HTTP POST request. The application framework’s JSON body parser is configured with a 1 MB limit to prevent denial-of-service memory exhaustion. The parser middleware throws a payload size error and responds with HTTP 413.

Common causes of HTTP 413

File upload exceeds reverse proxy client_max_body_size

An intermediary web server or reverse proxy (such as NGINX or Envoy) enforces a maximum body buffer limit (e.g., default 1 MB in NGINX) that the uploaded file exceeds.

Application-level body parser limit exceeded

The backend framework or parser middleware (e.g., express.json({ limit: '100kb' }) or body-parser) intercepts and rejects payloads exceeding configured limits.

Cloud API Gateway or Serverless payload restriction

A cloud platform or managed API gateway enforces a hard maximum payload limit (such as AWS API Gateway’s 10 MB limit or Lambda’s 6 MB payload limit).

Large batch mutation or JSON array transmission

A client attempts to send thousands of records in a single synchronous POST or PUT request, exceeding server memory or request size quotas.

Headers you may encounter

  • Retry-After: Indicates how long the client should wait before retrying, if the size limitation is temporary.
  • Connection: close: Prevents the client from continuing to transmit remaining bytes over the current TCP connection.
  • Content-Type: Typically application/problem+json (RFC 7807) detailing the maximum allowed body size.

Troubleshooting flow

When troubleshooting an HTTP 413 error, follow this structured diagnostic path:

HTTP 413 Payload Too Large
  |
  +-- What is the size of the request payload?
        |
        +-- < 1 MB: Check application framework body-parser configuration.
        |
        +-- > 1 MB to 10 MB: Check reverse proxy (NGINX client_max_body_size).
        |
        +-- > 10 MB: Consider cloud gateway limits or direct cloud storage uploads.

What to check before changing backend code

Before increasing server buffer limits, consider architectural best practices:

  1. Check the Content-Length header in client requests.
  2. Inspect NGINX client_max_body_size and Apache LimitRequestBody settings.
  3. Review framework middleware limits (express.json(), express.urlencoded(), Spring max-file-size).
  4. Check if files should be uploaded directly to cloud object storage (e.g., S3 pre-signed URLs) rather than proxied through application servers.
  5. Evaluate whether large batch API operations should be broken into paginated or asynchronous chunks.

How to verify the fix

Test upload behavior with curl using a sample binary payload:

curl -i -X POST https://api.example.test/v1/documents/upload \
  -H "Authorization: Bearer test-token" \
  -H "Content-Type: application/pdf" \
  --data-binary "@document.pdf"

Verify that the response returns 200 OK or 201 Created when the payload is within the permitted size threshold.

Remediation paths to evaluate

If uploading large media files

Architect direct client-to-storage uploads using pre-signed URLs (AWS S3, Google Cloud Storage, or Azure Blob Storage) to bypass application server bandwidth and memory constraints entirely.

If configuring reverse proxies

Increase the allowed body size in NGINX configuration:

server {
    client_max_body_size 25M;
}

If transmitting batch data

Split large JSON arrays into smaller batches (e.g., 500 items per request) or implement streaming APIs.

FAQ

What was HTTP 413 originally named?

In older specifications like RFC 2616, HTTP 413 was named Request Entity Too Large. RFC 7231 and RFC 9110 officially renamed it to Payload Too Large to align with modern HTTP semantics.

Does 413 mean the server ran out of disk space?

Not necessarily. HTTP 413 usually indicates that a pre-configured policy threshold was exceeded before the server even attempted to write the payload to disk.

Can a client retry a 413 request?

Only if the client reduces the payload size or if a Retry-After header indicates that the rejection was due to temporary server capacity constraints.

Key takeaway

HTTP 413 Payload Too Large indicates that the request body exceeded the maximum size permitted by a reverse proxy, API gateway, or application parser. Rather than simply raising server limits indiscriminately, evaluate direct-to-storage uploads or batch pagination for large payloads.