# API Gateway Payload Limits: 10MB REST Cap, 128KB WebSocket Limit, and Workarounds

The Amazon API Gateway payload limit is a hard cap of 10 MB for REST and HTTP APIs and 128 KB for WebSocket APIs, returning an HTTP 413 Payload Too Large error when request or response bodies exceed these quotas. Amazon Web Services enforces these boundaries at the edge proxy layer before downstream compute runs. Architectures requiring larger payloads bypass API Gateway using direct Amazon S3 presigned URLs or persistent cloud workspaces for autonomous agent pipelines.

Source: https://fast.io/resources/api-gateway-payload-limit/
Author: [Tom Langridge](https://fast.io/authors/tom-langridge/)
Last reviewed: 2026-10-05

## What Are the Amazon API Gateway Payload Limits?

The Amazon API Gateway payload limit is a hard cap of `10 MB` for REST and HTTP APIs and `128 KB` for WebSocket APIs, returning an HTTP 413 Payload Too Large error when request or response bodies exceed these quotas. Amazon Web Services (AWS) enforces these boundaries at the managed reverse proxy layer before any downstream compute, such as an AWS Lambda function or a containerized backend, ever receives the incoming byte stream.

In distributed cloud systems, API Gateway is the centralized traffic controller for modern applications. However, engineering teams frequently hit these rigid payload quotas when transmitting file attachments, multimedia assets, large batch JSON records, or autonomous agent execution logs. Because AWS designates payload limits as fixed service quotas, submitting a quota increase request in the AWS Service Quotas console or filing an AWS Support ticket will not lift the `10 MB` cap. Designing reliable distributed backends requires understanding how these constraints operate across every API architecture.

| API Type | Maximum Payload Limit | Frame or Message Limit | Default Integration Timeout | Can Quota Be Increased? |
| --- | --- | --- | --- | --- |
| REST API | `10 MB` | Not applicable | `29 seconds` | No |
| HTTP API | `10 MB` | Not applicable | `30 seconds` | No |
| WebSocket API | `128 KB` | `32 KB` frame size | `29 seconds` | No |
| AWS Lambda Integration | `6 MB` (synchronous) | Not applicable | Configurable up to 15 minutes | No |

For WebSocket APIs, the payload constraints are even tighter. While REST and HTTP endpoints accept payloads up to `10 MB`, WebSocket connections enforce a maximum message payload size of `128 KB` and an individual frame size limit of `32 KB`. Amazon API Gateway restricts WebSocket message payloads to 128 KB with a 32 KB maximum frame size, closing connections that exceed the limit with status code 1009. If a backend service or client attempts to emit a message between `32 KB` and `128 KB` over an established socket connection, the message must be broken into frames of `32 KB` or smaller. If a message or single frame exceeds these thresholds, API Gateway terminates the connection with WebSocket close code 1009 (Message Too Big).

A frequent point of confusion for backend teams is the difference between an HTTP 413 Payload Too Large error and an HTTP 502 Bad Gateway error. API Gateway enforces a `10 MB` cap, but AWS Lambda enforces its own hard limit of `6 MB` for synchronous request and response payloads. When an application routes a `7 MB` payload through API Gateway to a synchronous Lambda integration, API Gateway accepts the payload because `7 MB` sits safely under the `10 MB` gateway limit. However, Lambda immediately rejects the invocation with a RequestEntityTooLargeException. Because the downstream integration failed without generating a valid HTTP response, API Gateway translates the failure into an HTTP 502 Bad Gateway response. Diagnosing this failure requires inspecting AWS CloudWatch integration metrics and Lambda execution logs rather than gateway-level request validation rules.

## Why API Gateway Buffers and Enforces Strict Body Ceilings

Amazon API Gateway manages multi-tenant proxy infrastructure operating at high concurrency across AWS regions. The service relies on internal memory buffers to parse incoming requests, evaluate access controls, run AWS WAF inspection rules, apply Apache Velocity Template Language (VTL) mapping templates, and handle TLS termination. Allowing unbounded payload sizes would expose shared gateway infrastructure to memory exhaustion, buffer bloat, and denial-of-service vulnerabilities triggered by slow clients streaming heavy payloads over congested networks.

To maintain predictable routing performance and protect multi-tenant fleet capacity, AWS enforces strict per-request buffering boundaries. When a client initiates a request, API Gateway buffers the entire payload in memory before applying integration transformations or dispatching the request to the upstream target. This buffering architecture introduces three critical operational constraints:

* **Base64 Encoding Inflation:** When transmitting raw binary files (such as images, compressed archives, or audio files) through a REST API using JSON payloads or multipart form data, the binary payload is frequently encoded as Base64 text. Base64 encoding expands raw data volume by roughly `33 percent` because every 3 binary bytes are converted into 4 ASCII characters. As a result, a raw binary file measuring `7.6 MB` expands to roughly `10.13 MB` in Base64 representation. While the source file is well below `10 MB` on disk, the inflated transmission payload trips the `10 MB` API Gateway ceiling and triggers an immediate HTTP 413 error.

* **Integration Timeout Pressures:** In addition to payload size caps, API Gateway enforces strict integration timeouts. Amazon API Gateway enforces a maximum integration timeout of 29 seconds for REST APIs by default, which can be raised only on Regional and private endpoints. While Regional and private REST APIs permit requesting timeout adjustments beyond `29 seconds`, AWS documentation notes that raising this quota can require a reduction in the account-level Regional request throttling quota. Edge-optimized REST APIs and HTTP APIs do not allow timeout increases under any circumstances. Uploading large payloads over mobile networks or degraded internet links consumes substantial upload time, increasing the risk that the connection exhausts its `29 seconds` execution window before the backend returns a response.

* **Cost and Data Transfer Overhead:** API Gateway charges for API calls in addition to data transfer out. Routing multi-megabyte payloads through API Gateway consumes gateway request processing resources that are far more expensive than direct object storage data transfers. Treating an API gateway as a file transfer bus introduces unnecessary infrastructure spend without providing corresponding application benefits.

## How to Offload Uploads with Amazon S3 Presigned URLs

The proven architectural pattern for handling payloads larger than `10 MB` in serverless and cloud-native applications is the Claim-Check pattern using Amazon S3 presigned URLs. Instead of transmitting raw file bytes through API Gateway, the application decouples control plane metadata from the data plane transfer. API Gateway handles authentication, validation, and presigned URL generation, while the client uploads raw bytes directly to Amazon S3.

This decoupled upload workflow operates in four discrete steps:

1. **Initiate Upload Request:** The client application makes a lightweight JSON request to API Gateway (for example, `POST /files/upload-request`). The body contains only file metadata, such as the intended filename, MIME content type, target directory, and total file size in bytes. Because this metadata payload is typically under `1 KB`, it executes in milliseconds and remains far below any gateway limits.

2. **Generate Presigned URL:** API Gateway routes the metadata request to a lightweight Lambda function. The function authenticates the user, verifies organizational permissions, validates that the requested file type and size comply with business rules, and invokes the AWS SDK to generate an Amazon S3 presigned URL with an expiration window (such as 15 minutes). The function returns the presigned URL and an assigned asset identifier back to the client.

3. **Direct Binary Upload:** The client receives the presigned URL and executes an HTTP PUT request directly against the Amazon S3 endpoint, streaming the raw binary payload across the wire. This binary transfer completely bypasses API Gateway and AWS Lambda, allowing uploads up to `5 GB` using a single HTTP PUT operation or up to `5 TB` using S3 multipart uploads.

4. **Process Completion:** Once the upload finishes, the client notifies the backend via an API call, or Amazon S3 automatically emits an S3 Event Notification to Amazon EventBridge, Amazon SQS, or AWS Lambda to trigger downstream processing, such as indexing, transformation, or thumbnail generation.

Here is a practical implementation of the presigned URL generation handler using the AWS SDK for JavaScript v3:

```typescript
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const s3Client = new S3Client({ region: process.env.AWS_REGION });

export async function handler(event: { body: string }) {
  const { fileName, fileType, fileSize } = JSON.parse(event.body);
  const MAX_ALLOWED_BYTES = 500 * 1024 * 1024;
  if (fileSize > MAX_ALLOWED_BYTES) {
    return {
      statusCode: 400,
      body: JSON.stringify({ error: "File exceeds the 500 MB organization limit." }),
    };
  }
  const objectKey = `uploads/${Date.now()}-${fileName}`;
  const command = new PutObjectCommand({
    Bucket: process.env.UPLOAD_BUCKET_NAME,
    Key: objectKey,
    ContentType: fileType,
  });
  const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 900 });
  return {
    statusCode: 200,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ uploadUrl: presignedUrl, objectKey: objectKey }),
  };
}
```

On the client side, uploading the binary file requires issuing a single fetch call with the binary blob:

```typescript
async function uploadFileToS3(presignedUrl: string, file: File) {
  const response = await fetch(presignedUrl, {
    method: "PUT",
    headers: {
      "Content-Type": file.type,
    },
    body: file,
  });
  if (!response.ok) {
    throw new Error(`Upload failed with status code ${response.status}`);
  }
  return true;
}
```

While Amazon S3 presigned URLs solve raw transfer limits for browser-based uploads, this architecture introduces operational complexity. Teams must configure Cross-Origin Resource Sharing (CORS) rules on the S3 bucket to allow client PUT requests, implement bucket lifecycle policies to clean up incomplete or orphaned uploads, and write bespoke orchestration code to handle retries and progress tracking. More importantly, simple object storage provides only raw binary persistence; it does not provide structured document extraction, team permissions, or automated semantic search.

## How Autonomous AI Agents and MCP Pipelines Bypass Payload Caps

While browser-to-S3 presigned uploads resolve single-user file transfers, autonomous AI agent pipelines, multi-agent frameworks, and coding assistants face a completely different set of payload bottlenecks. When software agents collaborate to analyze technical specifications, parse large codebases, generate multi-megabyte audit reports, or process legal contracts, routing files through traditional API gateways fails for two distinct reasons: network gateway payload limits and language model context window exhaustion.

Autonomous agent tools communicating over Model Context Protocol (MCP) or custom REST interfaces often attempt to transmit large JSON execution states, database extracts, or document packages across API boundaries. Attempting to send an `18 MB` code repository dump or a `25 MB` document batch through API Gateway triggers an immediate HTTP 413 error. Similarly, transmitting streaming reasoning tokens or multi-agent messaging over WebSocket connections crashes against the `128 KB` message ceiling.

Even if an engineering team bypasses API Gateway using S3, passing raw document content directly to an AI model introduces severe context window limitations. Documented Claude mechanics illustrate this boundary clearly: Anthropic documentation specifies that a Claude chat conversation accepts up to `20 files` at up to `500 MB` each, while Claude Projects accepts individual files up to `30 MB` each with no fixed file count cap. However, the practical ceiling on any Claude Project is whether the total combined content fits within Claude's active context window. Ingesting dozens of multi-megabyte documents into prompt attachments inflates token consumption, degrades retrieval precision, and ultimately exhausts the context window.

The modern architectural solution for agentic workflows is decoupling data persistence from model context using persistent, intelligent cloud workspaces. Instead of streaming entire files through API gateways or loading raw documents into prompts, the corpus resides in a centralized workspace that indexes content on arrival.

Fast.io provides this intelligent workspace substrate for agentic teams and multi-agent systems. Rather than forcing agents to manage raw S3 buckets, CORS headers, and manual chunking logic, team assets land directly inside a shared Fastio workspace through direct uploads or automated Cloud Sync from Google Drive, Dropbox, Box, and OneDrive.

When Intelligence Mode is enabled on a workspace, Fast.io automatically indexes incoming files for hybrid search, combining full-text search, semantic search, and metadata filtering. Autonomous agents connect to the workspace through the remote Model Context Protocol server at `https://mcp.fast.io/mcp/tools` over Streamable HTTP, signing in with OAuth in the browser or sending an `Authorization: Bearer <api key>` header on the connection. Instead of transferring a `40 MB` PDF across API Gateway or stuffing it into prompt context, the agent uses MCP search tools to run natural language queries across the indexed workspace, retrieving only the precise, citation-backed paragraphs needed to complete its reasoning step.

For structured document processing, Fast.io provides [Metadata Views](/product/document-data-extraction/). Metadata Views turn unstructured documents into live, queryable database spreadsheets. Users describe the target fields in natural language, and the system extracts typed attributes (such as dates, financial figures, policy numbers, or contract counterparties) across PDFs, spreadsheets, and scanned documents without manual OCR rules. Agents can inspect schemas and query extracted metadata via MCP without handling raw file payloads.

Multi-agent collaboration also requires rigorous governance. Fast.io provides per-file version history for concurrent agent edits, ensuring changes remain auditable and recoverable. The append-only audit log records every agent and human action, establishing clear provenance for automated modifications. When an agent finishes assembling project workspaces and assets, Fast.io supports ownership transfer, allowing an automated workflow to transfer organizational administration to human stakeholders while retaining operational access.

Getting started is straightforward. Creating an account is free; doing real work requires an organization on a paid subscription. Monthly plans start with a 14-day free trial, which requires a credit card. Subscription plans are Starter at `$9.99/mo` (`250 GB` storage, 3 seats, 5 workspaces, and `100,000` monthly AI credits), Business at `$49.99/mo` (`5 TB` storage, 10 seats, 50 workspaces, and `600,000` monthly AI credits), and Enterprise at `$199.99/mo` (30 seats included with additional seats at `$1` a seat up to `200 seats`, `25 TB` storage, 200 workspaces, and `3,000,000` monthly AI credits). Maximum upload sizes scale from `25 GB` on Starter, to `50 GB` on Business, and `100 GB` on Enterprise. Explore architectural patterns on the [storage for agents](/storage-for-agents/) page and evaluate options on the [pricing page](/pricing/).

## Comparing Chunked Transfers, Compression, and Gateway Alternatives

When application requirements dictate that data must travel through HTTP streams or WebSocket connections rather than out-of-band object storage, engineering teams can evaluate several transport-level techniques and gateway alternatives.

* **Payload Compression with Gzip or Brotli:** Clients can compress request bodies using Gzip or Brotli and include the corresponding `Content-Encoding: gzip` or `Content-Encoding: br` HTTP header. For repetitive text payloads, log archives, or massive JSON files, compression frequently reduces payload volume by `60 to 80 percent`, allowing an uncompressed `20 MB` JSON payload to compress down to `4 MB` and pass beneath the `10 MB` limit. However, there is a critical caveat: if API Gateway is configured with request validation, VTL request mapping templates, or AWS WAF body inspection rules, the gateway decompresses the body in memory to inspect its contents. If the decompressed payload exceeds `10 MB`, API Gateway rejects the request with an HTTP 413 error. Compression functions reliably only when API Gateway acts as a pure pass-through proxy to an HTTP backend capable of handling decompression directly.

* **WebSocket Message Framing:** In API Gateway WebSocket APIs, messages larger than `32 KB` must be fragmented into frames of `32 KB` or smaller to comply with the frame-size quota. While this fragmentation satisfies the frame constraint, the overall reconstructed message payload must still remain under `128 KB`. For streaming large LLM completion streams or real-time agent output over WebSockets, backends should stream discrete token chunks (typically a few kilobytes each) rather than buffering and transmitting large multi-megabyte payloads in a single burst.

* **S3 Multipart Uploads for Massive Datasets:** When files range from `100 MB` up to `5 TB`, single-part HTTP PUT operations become unreliable because any network interruption forces the client to restart the entire transfer from byte zero. In this scenario, clients initiate an Amazon S3 Multipart Upload via API Gateway metadata coordination, break the source asset into discrete parts (from `5 MB` to `5 GB` each), upload each part directly to S3 concurrently, and issue a completion request to reassemble the object.

* **Application Load Balancers (ALB) and Network Load Balancers (NLB):** For architectures requiring multi-megabyte request streams without object storage offloading, replacing API Gateway with an AWS Application Load Balancer or Network Load Balancer provides relief. ALBs routing traffic directly to Amazon Elastic Container Service (ECS), Amazon Elastic Kubernetes Service (EKS), or Amazon EC2 instances do not impose the `10 MB` API Gateway ceiling. On backend container instances, reverse proxies like Nginx can configure `client_max_body_size 100M;` or higher to accept large streaming payloads. Note that when an ALB targets AWS Lambda functions, the ALB enforces a strict `1 MB` payload limit for Lambda integrations, which is more restrictive than API Gateway's `10 MB` cap.

| Architecture Pattern | Maximum Supported Payload | Optimal Use Case | Primary Operational Tradeoff |
| --- | --- | --- | --- |
| API Gateway Direct | `10 MB` (REST / HTTP), `128 KB` (WebSocket) | Standard microservice REST APIs and low-latency JSON RPC | Fixed, non-configurable payload ceiling |
| S3 Presigned URLs | `5 GB` (single PUT), `5 TB` (multipart) | User-facing web file uploads and media intake | Requires S3 CORS configuration and multi-step client logic |
| ALB or NLB to Containers | Configurable (e.g. `100 MB` and higher via Nginx) | High-throughput streaming ingest and legacy monoliths | Requires managing container infrastructure and auto-scaling |
| Persistent Workspaces (MCP) | `25 GB` to `100 GB` per file | Autonomous AI agents, multi-agent teams, and LLM RAG pipelines | Requires workspace indexing and MCP-compatible agent tooling |

Selecting the appropriate architecture depends on whether your payload represents ephemeral operational traffic or persistent business knowledge. For high-frequency API commands, staying within API Gateway's `10 MB` quota is standard practice. When working with media files, S3 presigned URLs provide the standard offloading mechanism. For autonomous AI agents processing large documents, multi-file codebases, and collaborative research, persistent intelligent workspaces eliminate both network payload limits and prompt context exhaustion.

## Frequently asked questions

### What is the maximum payload size for AWS API Gateway?

The maximum payload size for Amazon API Gateway is `10 MB` for both REST APIs and HTTP APIs. For WebSocket APIs, the maximum message payload size is `128 KB`, with an individual frame size limit of `32 KB`. These quotas apply to both request and response bodies across all supported AWS regions.

### Can you increase the API Gateway `10 MB` limit?

No, the `10 MB` payload limit in Amazon API Gateway is a hard, non-configurable service quota. AWS does not permit quota increases for this limit through the AWS Service Quotas console, support tickets, or enterprise support agreements. Applications requiring larger payloads must decouple data transfers using external storage.

### How do you handle payloads larger than `10 MB` in API Gateway?

The standard architectural pattern for payloads exceeding `10 MB` is offloading the transfer to Amazon S3 using presigned URLs. The client requests a presigned URL from API Gateway via a lightweight JSON metadata call, uploads the raw binary payload directly to S3 via HTTP PUT, and notifies the backend upon completion. For AI agent workflows, files can be uploaded to persistent cloud workspaces that index content for hybrid retrieval via Model Context Protocol.

### Why do I receive a 502 Bad Gateway error instead of 413 when uploading a `7 MB` file?

When API Gateway integrates synchronously with AWS Lambda, Lambda enforces its own `6 MB` payload limit on requests and responses. If you send a `7 MB` payload, API Gateway accepts it because it is under the `10 MB` gateway limit, but Lambda rejects the call with a RequestEntityTooLargeException. Because the downstream integration failed to return a valid HTTP response, API Gateway surfaces the failure as an HTTP 502 Bad Gateway error rather than an HTTP 413.

### How does the `128 KB` WebSocket payload limit work with the `32 KB` frame size?

In API Gateway WebSocket APIs, individual WebSocket data frames are capped at `32 KB`, while the total reconstructed message payload is capped at `128 KB`. If you transmit a message between `32 KB` and `128 KB`, the sender must split the message into consecutive `32 KB` frames. Exceeding either the `32 KB` frame limit or the `128 KB` message ceiling causes API Gateway to terminate the connection immediately with close code 1009.

### Does compressing request bodies with Gzip bypass the `10 MB` API Gateway limit?

Compressing request bodies with Gzip or Brotli reduces the size of the payload on the wire, allowing large JSON or text datasets to pass under the `10 MB` network threshold. However, if API Gateway has request validation, body mapping templates, or AWS WAF inspection enabled, the gateway decompresses the body in memory. If the uncompressed body exceeds `10 MB`, API Gateway rejects the request with an HTTP 413 error.

### How do AI agents and MCP servers handle documents exceeding API Gateway payload caps?

Autonomous agents avoid payload caps and context window exhaustion by decoupling file storage from API requests. Documents are stored in persistent, intelligent cloud workspaces that auto-index content for semantic and full-text search. The agent connects via Model Context Protocol (MCP) and executes targeted queries, retrieving only the relevant text snippets and metadata rather than transmitting multi-megabyte files across gateway connections.

## Sources

- [Amazon API Gateway Developer Guide: Quotas for configuring and running a REST API in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-execution-service-limits-table.html): Amazon API Gateway enforces a maximum integration timeout of 29 seconds for REST APIs by default, which can be raised only on Regional and private endpoints.
- [Amazon Web Services: Amazon API Gateway Important Notes](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html): Amazon API Gateway restricts WebSocket message payloads to 128 KB with a 32 KB maximum frame size, closing connections that exceed the limit with status code 1009.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.