Fix API Gateway 502 errors from a Lambda proxy integration

The Lambda invocation runs, but API Gateway returns 502 to the browser. The integration may be receiving a response shape it cannot interpret.

Why this happens

A function error or a response that does not match the configured integration payload format can produce a gateway failure. REST API and HTTP API integrations have different details that must not be mixed blindly.

Step-by-step solution

1. Inspect API Gateway and Lambda logs using the request identifiers. Confirm the API type and configured payload format version.

2. Return the response structure required by that integration, including a correctly encoded body where required. Keep unexpected exceptions out of the normal success path.

3. Test through the actual gateway endpoint rather than only the Lambda console. Check headers and binary-response handling if the body is not ordinary JSON.

Worked example

For a conventional REST API Lambda proxy response, return statusCode: 200 and body containing a JSON string, rather than a nested object where a string is expected.

Verify the fix

Exercise a successful request and a controlled application error through API Gateway. The client should receive the intended status and body, not a generic integration failure.

Prevent a repeat

Add response-contract tests and document the selected payload version. Do not expose raw exception traces to clients while debugging.

Reference

Official documentation or standards guidance

An original Gistmax troubleshooting guide. Scenarios and sample values are illustrative; configuration depends on your software version and environment. Cover diagram: Gistmax Tutorials.