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 (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.

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.

• Can ChatGPT Access Google Drive? Permissions, Limits & WorkaroundsChatGPT can access Google Drive files through its native integration, but only by retrieving individual user-selected...
• Google Drive Search API: Query Syntax, Limits, and Agent PipelinesThe Google Drive Search API allows applications to query file metadata and document text through the files.list...
• Can Gemini Access Google Drive? Extension Limits, Permissions, and MCP SearchGoogle Gemini connects to Google Drive through the Google Workspace extension (@Google Drive) for conversational...
• How to Connect Python to Dropbox: SDK Guide vs Intelligent Agent WorkspacesThe Dropbox Python API enables programmatic file manipulation using the dropbox package, but requires developers to...
• Dropbox Search API Guide: How to Search Files ProgrammaticallyThe Dropbox Search API v2 allows developers to search files programmatically using scoped queries, extension filters,...
• Microsoft Graph API for OneDrive: Endpoints, Delta Queries, and Agent Storage ArchitectureAutonomous AI agents querying Microsoft OneDrive via the Microsoft Graph API frequently stall on delta query...

More on this subject: Agent Integrations and APIs (171 guides)

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.

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:

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:

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.

Decouple Heavy Agent Data from API Gateway Limits

Connect your autonomous agents and LLMs to persistent, indexed cloud workspaces using the Fast.io MCP server. Monthly plans start with a 14-day free trial.

Start 14-Day Trial

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. 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 page and evaluate options on the pricing page.

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.

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.