api gateway: 502 Bad Gateway on lambda proxy integration

TL;DR

Lambda proxy integration demands a specific JSON response shape (statusCode, headers, body as a string); anything else (a raw object, a non-string body, an exception) becomes a 502. Fix the handler's return shape and the 502s stop.

Error

api gateway: 502 Bad Gateway on lambda proxy integration

Steps

1. Confirm the integration type: check that the method uses Lambda proxy integration (not the custom mapping kind). Expected: proxy integration, where the response contract applies.
2. Read the Lambda logs: look for the actual return value or exception from the invocation behind the 502. Expected: you see the malformed return (missing statusCode, object body, or a thrown error).
3. Fix the return shape: return an object with a numeric statusCode and a string body (stringify JSON bodies), plus headers as needed. Expected: the shape matches the proxy contract.
4. Handle errors explicitly: catch exceptions in the handler and return a 500-shaped response instead of throwing. Expected: failures become 500s with bodies, not 502s.
5. Redeploy the API (proxy integrations need a deployment to pick up changes) and re-test. Expected: 200s with correct bodies.

When to use

• API Gateway returns 502 with a Lambda proxy backend
• New handlers that never returned the proxy shape
• 502s that appear only on certain routes

When not to use

• Lambda timeouts (504, not 502)
• IAM permission errors invoking Lambda (different error)

Tool compatibility

• API Gateway REST/HTTP APIs, Lambda proxy integration response contract

Variant phrasings

lambda proxy 502 malformed response

Stringify the body and include statusCode; the proxy contract is strict.

api gateway 502 after code change

The new code path returns something unserializable or throws; check the Lambda logs.

Why it happens

Proxy integration passes the Lambda return value straight through API Gateway's serializer with no transformation. The serializer only understands the documented shape, so any deviation (including uncaught exceptions) fails serialization and surfaces as a 502.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstt5bjrFVFHhEGMIbt4g_DA