API Gateway Payload Limits: The 10MB Ceiling and What To Do When You Hit It

The limits

API Gateway enforces the following payload size limits. These are hard limits — you cannot increase them by request:

| API Type | Request payload | Response payload | |---|---|---| | REST API | 10 MB | 10 MB | | HTTP API | 10 MB | 10 MB | | WebSocket API | 128 KB per message | 128 KB per message |

For REST and HTTP APIs, exceeding the request limit returns HTTP 413 ({"message": "Request Too Large"}). Exceeding the response limit truncates the response — the client receives a partial body, usually causing a JSON parse error or a 502 from API Gateway.

Lambda's own payload limits compound the problem

Lambda has separate, lower limits that hit before API Gateway's:

• Synchronous invocation (what API Gateway uses): 6MB request payload, 6MB response payload
• Asynchronous invocation: 256KB

If your Lambda integration processes large payloads, Lambda's 6MB limit is the binding constraint, not API Gateway's 10MB. A 7MB file upload fails with a Lambda error, not a 413 from API Gateway.

Handling large file uploads: presigned URLs

The standard pattern for large file uploads bypasses API Gateway entirely. The client requests a presigned URL from your API, then uploads directly to S3:

Client → API Gateway → Lambda: "give me an upload URL"
Lambda → S3: create presigned PUT URL
Lambda → API Gateway → Client: presigned URL

Client → S3: PUT file directly (no API Gateway involved)

import boto3

def handler(event, context):
    s3 = boto3.client('s3')

    # Generate presigned URL for direct client upload
    presigned_url = s3.generate_presigned_url(
        'put_object',
        Params={
            'Bucket': 'uploads-bucket',
            'Key': f"uploads/{event['pathParameters']['user_id']}/{event['queryStringParameters']['filename']}",
            'ContentType': event['queryStringParameters']['content_type'],
        },
        ExpiresIn=300  # 5 minutes
    )

    return {
        'statusCode': 200,
        'body': json.dumps({'upload_url': presigned_url})
    }

The client uploads directly to S3 with a PUT request using the presigned URL. The file size limit is S3's: 5GB for a single PUT, 5TB for multipart upload.

After upload completes, trigger processing via an S3 event notification to Lambda — keeping the heavy computation out of the synchronous API request path entirely.

Handling large responses: presigned download URLs

The same pattern applies to downloads. Instead of returning large data through API Gateway, return a presigned GET URL:

def handler(event, context):
    s3 = boto3.client('s3')
    report_key = f"reports/{event['pathParameters']['report_id']}.csv"

    # Check the file size first
    head = s3.head_object(Bucket='reports-bucket', Key=report_key)
    size_mb = head['ContentLength'] / (1024 * 1024)

    if size_mb > 8:  # leave buffer below 10MB limit
        # Return a presigned URL for direct download
        download_url = s3.generate_presigned_url(
            'get_object',
            Params={'Bucket': 'reports-bucket', 'Key': report_key},
            ExpiresIn=900  # 15 minutes
        )
        return {
            'statusCode': 202,
            'body': json.dumps({'download_url': download_url})
        }
    else:
        # Small enough to return inline
        obj = s3.get_object(Bucket='reports-bucket', Key=report_key)
        return {
            'statusCode': 200,
            'headers': {'Content-Type': 'text/csv'},
            'body': obj['Body'].read().decode('utf-8')
        }

import json

# Lambda streaming handler (Python)
def handler(event, context):
    # Use response streaming
    yield json.dumps({"status": "starting"}).encode()

    for chunk in generate_large_dataset():
        yield chunk.encode()

    yield json.dumps({"status": "complete"}).encode()

WebSocket APIs and the 128KB message limit

WebSocket APIs have a much smaller per-message limit. For real-time applications sending large data:

# Split large data into chunks before sending over WebSocket
import json

def send_large_payload(apigw_client, connection_id, data: str):
    MAX_CHUNK = 100_000  # bytes, leave buffer below 128KB
    chunks = [data[i:i+MAX_CHUNK] for i in range(0, len(data), MAX_CHUNK)]
    total = len(chunks)

    for i, chunk in enumerate(chunks):
        message = json.dumps({
            "type": "chunk",
            "index": i,
            "total": total,
            "data": chunk
        })
        apigw_client.post_to_connection(
            ConnectionId=connection_id,
            Data=message.encode()
        )

The client reassembles chunks. This is simpler than it sounds for structured data — the alternative is an out-of-band download URL sent over WebSocket, which is cleaner for large one-time transfers.