API Gateway and Lambda

The most common serverless pattern on AWS, and the source of one error more than any other: {"message": "Internal server error"} with a 502, caused not by your code failing but by returning the wrong shape.

This page is mostly about getting that shape right.

Proxy integration

With AWS_PROXY, API Gateway passes the entire request to your function and expects the entire HTTP response back. Your function handles routing, status codes and headers.

aws apigatewayv2 create-integration --api-id "$API_ID" \
  --integration-type AWS_PROXY \
  --payload-format-version 2.0 \
  --integration-uri "arn:aws:lambda:eu-west-1:123456789012:function:orders" \
  --timeout-in-millis 29000

The alternative, non-proxy AWS integration, uses mapping templates to shape both directions. It lets you keep transformation out of your code, at the cost of VTL in your infrastructure config and error mapping that depends on matching error strings. Use proxy unless you have a specific reason not to.

The response shape

This is the whole ball game. A proxy integration requires an object with specific keys, and anything else is a 502:

def handler(event, context):
    return {
        "statusCode": 200,
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps({"orderId": "A-4821"})
    }

Three rules that cause nearly every 502:

body must be a string. Returning a dict is the single most common mistake, json.dumps() it.

return {"statusCode": 200, "body": {"ok": True}}        # 502
return {"statusCode": 200, "body": json.dumps({"ok": True})}   # correct

statusCode must be present and an integer. "200" as a string fails.

An unhandled exception is a 502, not a 500 with your error. Catch and return deliberately:

def handler(event, context):
    try:
        return {"statusCode": 200, "body": json.dumps(do_work(event))}
    except NotFound:
        return {"statusCode": 404, "body": json.dumps({"error": "not found"})}
    except Exception:
        logger.exception("unhandled")
        return {"statusCode": 500, "body": json.dumps({"error": "internal"})}

The gateway's error message never tells you which of these it was. The function's CloudWatch log does, which is why the log group is the first place to look, not the gateway.

Payload format 1.0 vs 2.0

HTTP APIs default to 2.0, REST APIs are always 1.0, and the event structures differ in ways that break code moved between them:

That last row is a real trap. Under 2.0, a function returning a plain object with no statusCode is treated as a successful JSON body with status 200, so a function that silently returns the wrong thing looks like it works. Under 1.0 the same return is a 502. Set statusCode explicitly either way.

Header names arrive lowercased, and event["headers"] in 2.0 joins multiple values with commas rather than providing a multi-value map.

Pin the format explicitly rather than relying on defaults:

--payload-format-version 2.0

Permissions

API Gateway needs permission to invoke the function. This is a resource-based policy on the Lambda, not an execution role:

aws lambda add-permission --function-name orders \
  --statement-id apigw-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:eu-west-1:123456789012:$API_ID/*/*"

Creating the integration in the console adds this automatically; creating it with the CLI, Terraform or CloudFormation does not, which is why a hand-built integration fails with:

Keep --source-arn scoped to your API. A wildcard principal with no source restriction lets any API Gateway in any account invoke your function.

CORS

Handled in two places, and getting it half right is worse than not doing it at all.

Preflight (OPTIONS), on an HTTP API this is configuration, and the gateway answers without invoking Lambda:

aws apigatewayv2 update-api --api-id "$API_ID" \
  --cors-configuration 'AllowOrigins=https://app.example.com,AllowMethods=GET,POST,PUT,DELETE,OPTIONS,AllowHeaders=content-type,authorization,AllowCredentials=true,MaxAge=300'

Actual responses: your function must still return the headers, because CORS applies to every response, not just the preflight:

CORS = {
    "Access-Control-Allow-Origin": "https://app.example.com",
    "Access-Control-Allow-Credentials": "true",
}
return {"statusCode": 200, "headers": {**CORS, "Content-Type": "application/json"}, "body": json.dumps(data)}

The classic symptom is a request that works in curl and fails in the browser with a CORS error, because the error response lacks the headers even though the success response has them. Return CORS headers on error paths too, or a 500 becomes an unhelpful CORS message that hides the real problem.

AllowCredentials=true cannot be combined with AllowOrigins=*; browsers reject it.

Timeouts

Two limits, and the smaller one wins:

• API Gateway: 29 seconds, a hard maximum on REST APIs. HTTP APIs also default to 30 seconds.
• Lambda: up to 15 minutes.

So a Lambda configured for five minutes behind API Gateway is cut off at 29 seconds, and the client gets a 504 while the function keeps running and billing. Configure the function timeout below the gateway's:

aws lambda update-function-configuration --function-name orders --timeout 25

For genuinely long work, return 202 immediately and do the work asynchronously, put a message on SQS or start a Step Functions execution, then let the client poll or receive a webhook.

Cold starts

A first invocation pays initialisation cost: container start, runtime boot, then your module-level code. Three things help, in order of effect:

Move work to module scope. Clients created inside the handler are rebuilt on every invocation:

import boto3
ddb = boto3.resource("dynamodb")          # once per container
table = ddb.Table("Orders")

def handler(event, context):
    return table.get_item(Key={...})      # reuses the connection

Keep the package small. A 200 MB deployment package initialises slower than a 5 MB one. Bundle only what you import.

Provisioned concurrency removes cold starts for a fixed hourly cost:

aws lambda put-provisioned-concurrency-config \
  --function-name orders --qualifier prod --provisioned-concurrent-executions 5

It requires a version or alias, not $LATEST. Use it for latency-sensitive user-facing paths and not for everything, since you pay whether or not the capacity is used.

Debugging a 502

In order:

# 1. Did the function even run?
aws logs tail /aws/lambda/orders --since 10m --follow

# 2. What did the gateway see?
aws logs filter-log-events --log-group-name /aws/apigw/orders \
  --filter-pattern '{ $.integrationError = "*" }' --max-items 5

No Lambda log at all means permissions. A log showing a successful run means the response shape is wrong. A log showing an exception means the code failed, and the 502 is hiding it, which is why you should catch exceptions and return a real status code.

Common errors

1. Response shape, unhandled exception, or missing permission, in that order of likelihood.

Missing lambda:add-permission for apigateway.amazonaws.com.

504 at 29 seconds. Lower the function timeout and make long work asynchronous.

Works in curl, CORS error in the browser. Error responses are missing CORS headers.

Quick reference

Key takeaways

• body must be a JSON string. Returning an object is the top cause of 502s.
• statusCode must be an integer, and under payload 2.0 its absence silently becomes a 200.
• An unhandled exception is a 502 that hides your error. Catch and return real codes.
• Payload 1.0 and 2.0 have different event shapes. Pin the version explicitly.
• API Gateway needs a resource-based permission on the function: console adds it, CLI does not.
• Return CORS headers on error responses too, or failures appear as CORS problems.
• 29 seconds is a hard ceiling. Set the function timeout below it and offload long work.
• Initialise clients at module scope: the cheapest cold-start improvement available.

Check your understanding

<MCQExercise exercise={{ id: 'aws-apigw-lambda-quiz1', title: 'A 502 from a function that succeeded', description: 'A Lambda behind API Gateway logs a successful execution and returns {"statusCode": 200, "body": {"orderId": "A-4821"}}. The client receives 502 Internal server error. Why?', options: [ { id: 'a', text: 'body must be a string. API Gateway cannot serialise an object, so json.dumps() is required' }, { id: 'b', text: 'The response is missing an isBase64Encoded field, which is mandatory' }, { id: 'c', text: 'statusCode 200 must be returned as the string "200" in proxy integrations' }, { id: 'd', text: 'The function needs a longer timeout for API Gateway to accept the response' }, ], correctId: 'a', explanation: 'A proxy integration hands the function's return value straight to the gateway as an HTTP response, and body is the raw response payload, so it must already be a string. Returning a dict means API Gateway cannot build a valid response and reports 502 with a generic message, even though the function ran perfectly and logged success. Wrap it in json.dumps(). This split between "the function worked" and "the client got a 502" is exactly why the Lambda log group is the first place to look.', wrongExplanations: { b: 'isBase64Encoded is optional and defaults to false; it only matters for binary responses.', c: 'The opposite: statusCode must be an integer, and a string value causes its own failure.', d: 'Timeouts produce a 504 after 29 seconds. This function returned promptly.', }, }} />

<MCQExercise exercise={{ id: 'aws-apigw-lambda-quiz2', title: 'Works in curl, fails in the browser', description: 'An API returns data correctly via curl. From the browser, successful requests work but any request that errors shows a CORS error instead of the error message. CORS is configured on the HTTP API. What is wrong?', options: [ { id: 'a', text: 'The error paths in the Lambda do not return the Access-Control-Allow-Origin header, and CORS applies to every response including errors' }, { id: 'b', text: 'CORS configuration on an HTTP API only covers GET requests' }, { id: 'c', text: 'The browser requires AllowOrigins to be set to * for error responses' }, { id: 'd', text: 'curl bypasses CORS, so the API is misconfigured for all requests and only appears to work' }, ], correctId: 'a', explanation: 'The gateway CORS configuration handles the OPTIONS preflight, but with a proxy integration every actual response comes from your function, so each one must carry the CORS headers itself, error paths included. When a 500 or 404 returns without them, the browser blocks the response and reports a CORS failure, hiding the real error entirely and sending people to debug the wrong thing. Define the headers once and spread them into every return, including the catch-all exception handler.', wrongExplanations: { b: 'AllowMethods lists which methods are permitted; the configuration is not restricted to GET.', c: 'A wildcard origin is not required and is incompatible with AllowCredentials=true.', d: 'curl ignores CORS because CORS is a browser security mechanism. The successful responses genuinely are correct.', }, }} />