Fix 413 payload too large on API Gateway

Quick Answer: The "413 Payload Too Large" error indicates that the client's request body size exceeds the maximum limit configured on your API Gateway or backend service. The most likely cause is an oversized request payload, such as a large file upload or extensive JSON data. First, review your API Gateway's integration request settings for payload size limits. Increase the `Content-Length` limit or adjust the `Request Payload Size Limit` setting. Expect the API call to succeed without a 413 error.

What Causes This Error

API Gateway's configured payload size limit (e.g., 10MB for AWS API Gateway) has been exceeded by the client's request.
The backend service (e.g., Lambda function, EC2 instance, or container) has its own payload size limit, which is smaller than the API Gateway's limit, leading to rejection before API Gateway can process it.
Web server (e.g., Nginx, Apache) or application server (e.g., Tomcat, Node.js Express) sitting in front of the actual API has a `client_max_body_size` or similar directive configured too low.
An intermediate proxy or load balancer between the client and API Gateway is enforcing a smaller payload size limit.
The client is sending an unnecessarily large request, such as unoptimized images, large uncompressed JSON/XML, or redundant data.
Incorrect `Content-Length` header sent by the client, reporting a smaller size than the actual payload, causing issues with streaming or partial reads at intermediate layers.

Step-by-Step Fixes

Fix 1: Increase API Gateway Payload Size Limit

For AWS API Gateway: Navigate to your REST API in the AWS console, select the specific method (e.g., POST /resource).,Under the 'Integration Request' section, locate 'HTTP Headers' or 'Mapping Templates'. While there isn't a direct 'payload size limit' setting per method, the default for REST APIs is 10MB. If using HTTP APIs, the default is 10MB.,For larger payloads exceeding 10MB, consider using S3 pre-signed URLs for direct client uploads to S3, then notify your API Gateway for processing, or use a custom domain with a CDN like CloudFront that allows larger body sizes (up to 20GB for PUT/POST).,If using a WebSocket API, the default message size limit is 128KB. Increase this limit in the 'Settings' tab of your WebSocket API.

Fix 2: Adjust Backend Service Payload Limits

For AWS Lambda: Increase the 'Memory' setting for your Lambda function. While not a direct payload limit, higher memory often correlates with increased temporary storage and processing capacity for larger payloads. The direct payload limit for synchronous invocation is 6MB, and 256KB for asynchronous.,For EC2/Containerized applications: If using Nginx, modify `nginx.conf` by adding or increasing `client_max_body_size` in `http`, `server`, or `location` blocks (e.g., `client_max_body_size 20M;`). Reload Nginx: `sudo systemctl reload nginx`.,For Node.js Express: Use `app.use(express.json({ limit: '20mb' }));` and `app.use(express.urlencoded({ limit: '20mb', extended: true }));` in your application setup.,For other backend frameworks, consult their documentation for specific request body size configuration parameters.

Fix 3: Optimize Client Request Payload

Review the data being sent by the client. Identify if any unnecessary fields, metadata, or redundant information can be removed.,Compress large text-based payloads (JSON, XML) using GZIP or Brotli compression at the client-side. Ensure the API Gateway and backend are configured to decompress these payloads (e.g., by checking for `Content-Encoding: gzip` header).,For large binary files (images, videos), implement a strategy to upload them directly to an object storage service like AWS S3 using pre-signed URLs. The client uploads to S3, then sends a smaller request to the API Gateway with the S3 object key for processing.,Implement client-side validation to prevent sending excessively large payloads in the first place, providing immediate feedback to the user.

Fix 4: Check Intermediate Proxies/Load Balancers

If your architecture includes an Application Load Balancer (ALB) or Network Load Balancer (NLB) in front of your API Gateway or backend, verify their configuration.,ALB has a default payload size limit of 1MB for HTTP/HTTPS requests. For larger payloads, consider using CloudFront in front of ALB, which supports larger body sizes.,Review any custom proxy configurations (e.g., HAProxy, Envoy) for directives like `client_max_body_size` or `max_body_size` and adjust them as needed.,Ensure all layers in your request path, from client to final backend, have consistent or sufficiently large payload limits.

Advanced Fixes

Advanced Fix 1: Integrate CloudFront with API Gateway for Large Payloads

Create an AWS CloudFront distribution. Configure your API Gateway as an origin for the CloudFront distribution.,Ensure your CloudFront behavior is configured to allow HTTP methods like PUT/POST and to forward appropriate headers, including `Content-Length`.,CloudFront supports much larger body sizes (up to 20 GB for PUT/POST requests), acting as a reverse proxy that can handle the larger payload before forwarding a potentially smaller, processed request or S3 reference to your API Gateway.

FAQs

Q: What is the default payload size limit for AWS API Gateway?

A: For AWS REST API Gateway, the default payload size limit is 10 MB (megabytes). For HTTP API Gateway, the limit is also 10 MB. For WebSocket APIs, the default message size limit is 128 KB (kilobytes).

Q: Can I increase the 10MB limit on AWS API Gateway directly?

A: No, you cannot directly increase the 10MB payload limit for REST or HTTP API Gateway methods. For payloads exceeding this, the recommended approach is to use S3 pre-signed URLs for direct client uploads to S3, and then have your API Gateway process the S3 object key. Alternatively, use CloudFront in front of your API Gateway, which supports larger body sizes (up to 20GB for PUT/POST).

Q: Does GZIP compression help with 413 errors?

A: Yes, GZIP or other compression methods can significantly reduce the actual size of the request payload sent over the network. If the compressed size falls within the API Gateway's limit, the 413 error can be avoided. Ensure both the client and API Gateway/backend are configured to handle `Content-Encoding` headers for compression/decompression.

Q: How do I determine which component is enforcing the 413 limit?

A: Start by checking the most restrictive limits. Begin with your API Gateway's default limits (10MB for REST/HTTP). If your payload is below this, check your immediate backend service (e.g., Lambda 6MB sync limit, Nginx `client_max_body_size`). Use `curl -v` or browser developer tools to inspect response headers; sometimes, a proxy will include its own headers (e.g., `Server: nginx`) that can indicate the source.