Integrating with Lambda

In a Lambda Proxy integration (the most common and recommended pattern), API Gateway passes the entire incoming request (path, query parameters, headers, body) as a structured event object to the Lambda function, and expects the function to return a response in a specific shape: {"statusCode": 200, "headers": {...}, "body": "..."} (with the body typically a JSON string, not a raw object). API Gateway handles translating this back into a proper HTTP response to the client.

A common early-development mistake is a Lambda function returning a plain object or just the intended response body directly, rather than wrapping it in this expected {statusCode, headers, body} structure — this causes a generic 500 error at the API Gateway layer that can be confusing to debug without knowing this specific contract.

Non-proxy (custom) integrations give more control — you can define mapping templates to transform the request before it reaches Lambda and the response before it reaches the client — but require meaningfully more configuration and are used far less often than the simpler, more common proxy integration pattern.

# Example Lambda Proxy integration response shape (Python)
import json

def handler(event, context):
    order_id = event['pathParameters']['id']
    return {
        'statusCode': 200,
        'headers': {'Content-Type': 'application/json'},
        'body': json.dumps({'orderId': order_id, 'status': 'shipped'})
    }