## 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
```text
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/pst_t5bjrFVFHhEGM_Ibt4g_DA