Webhook Relay

413 Payload Too Large (Request Entity Too Large): how to fix it

413 Payload Too Large (also "Request Entity Too Large", and "Content Too Large" in the current HTTP spec) means the request body is bigger than a server or proxy in the chain is willing to accept. The request was rejected before your code ran. The fix is to find which layer has the limit and raise it, or send less data.

HTTP/1.1 413 Request Entity Too Large
Server: nginx
Content-Type: text/html

<html><head><title>413 Request Entity Too Large</title></head>
<body><center><h1>413 Request Entity Too Large</h1></center><hr><center>nginx</center></body></html>

Common causes

  • A web server default. nginx allows only 1 MB of body by default.
  • A framework body parser. Express's express.json() defaults to 100 kB.
  • A CDN, gateway or serverless limit in front of your app.
  • An unexpectedly large request. A base64-encoded file in JSON, a bulk API call, or a webhook that embeds a document.

Where the limits are

Every hop between the client and your code can have its own limit, and the smallest one wins.

LayerDefault limitHow to change it
nginx1 MBclient_max_body_size 50m; in http, server or location
ingress-nginx (Kubernetes)1 MBAnnotation nginx.ingress.kubernetes.io/proxy-body-size: "50m"
Apache1 GB (since 2.4.54)LimitRequestBody
IISabout 28.6 MBmaxAllowedContentLength in requestFiltering
Express / body-parser100 kBexpress.json({ limit: '10mb' })
Cloudflare100 MB (Free, Pro), 200 MB (Business), 500 MB (Enterprise)Plan-dependent; upload larger files directly to storage
AWS API Gateway10 MBFixed; use presigned S3 uploads for larger files
AWS Lambda6 MB synchronous request payloadFixed; pass a reference to S3 instead

How to fix it

As a visitor: reduce the file size (compress the image or video, split the upload) or contact the site. You can't raise the limit yourself.

As a developer or ops:

  1. Find the layer that rejected it. The response's Server header and body usually tell you. An nginx HTML page means nginx; a JSON PayloadTooLargeError means your Node app; a branded error page means the CDN. nginx also logs client intended to send too large body.
  2. Raise the limit at that layer, then check the next one. Raising nginx to 50 MB does nothing if body-parser still stops at 100 kB.
  3. Reload and test with a body just under and just over the new limit: curl -X POST --data-binary @big.json -H 'Content-Type: application/json' https://example.com/api/.
  4. For large files, don't send them through your API at all. Issue a presigned upload URL to object storage and pass a reference.

Example for nginx:

server {
    client_max_body_size 50m;

    location /webhooks/ {
        client_max_body_size 50m;
        proxy_pass http://127.0.0.1:3000;
    }
}

413 on a webhook endpoint

Most webhook payloads are small JSON documents, but some providers embed files, documents, images or very large event batches. When one goes over a limit anywhere in your stack, the provider sees a 413. Some retry it, which can't help because the payload stays the same size; others record it as a permanent failure. Either way, the event doesn't arrive.

Fix the limits on every hop of the webhook path, the same way as above, and keep body parsing for webhook routes separate from the rest of the app if you need a higher limit only there. Keep the raw body available for signature verification.

If webhooks pass through Webhook Relay on their way to you, the bucket has its own limit: 4 MB by default. Enable Large webhooks in the bucket settings to receive and forward payloads up to 40 MB, or contact support for 100 MB or more. See large webhooks. Your destination (often nginx at 1 MB) still needs a matching limit.

When to return 413 from your own API

Return 413 when the body exceeds a limit you enforce, and say what the limit is in the response body so clients can adjust. Reject early, from Content-Length, before reading the whole body. If the body is the right size but the content is invalid, use 400 or 422 instead. For overly long URLs the code is 414 URI Too Long, and for oversized headers it's 431 Request Header Fields Too Large.

Frequently asked questions

What does 413 Payload Too Large mean?

HTTP 413 means the request body is larger than the server, or a proxy in front of it, is willing to accept. The current HTTP spec calls it 413 Content Too Large; older names are Payload Too Large and Request Entity Too Large. The request was rejected without being processed.

How do I fix 413 Request Entity Too Large in nginx?

Raise client_max_body_size, which defaults to 1 megabyte. Set it in the http, server or location block, for example client_max_body_size 50m, then reload nginx with nginx -s reload. On Kubernetes ingress-nginx, use the nginx.ingress.kubernetes.io/proxy-body-size annotation instead.

Why does Express return PayloadTooLargeError: request entity too large?

The body parser in express.json() and express.urlencoded() has a default limit of 100kb. Pass a higher limit, for example express.json({ limit: '10mb' }). For file uploads, stream the body with a multipart parser instead of buffering it.

I raised the limit and still get 413. Why?

Another layer has its own limit. Check every hop between the client and your code: a CDN such as Cloudflare, a load balancer or API gateway, the ingress controller, the web server and the framework's body parser. The response body or Server header usually shows which one rejected the request.

What is the maximum webhook payload size?

It depends on the provider and the receiver. Most providers keep webhook payloads small, often well under 1 megabyte, but some include documents or files. Webhook Relay accepts up to 4 MB by default and up to 40 MB with Large webhooks enabled on the bucket.

Related