AWS API Gateway Support
Fixing API Gateway 502 Bad Gateway with Lambda proxy.
A 502 from API Gateway means it could not use what the backend returned. With Lambda proxy integration the usual cause is a response in the wrong shape, or a function that crashed before returning one. Execution logs tell us which, and the fix is usually small.
When You Need This
The situations where this work pays for itself.
Signs it is time
- Clients get 502 Bad Gateway or 'Internal server error' from a Lambda-backed API
- Logs show 'Malformed Lambda proxy response'
- The function works in the Lambda test console but fails through the API
- 502 appears only on certain inputs or large responses
- The error began after a runtime or code change
What you get
- The root cause with the execution log evidence
- A corrected handler or response wrapper
- Access and execution log settings in infrastructure as code
- Alarms on 5XXError and Lambda Errors
How we do it
A clear, safe process you can follow along with.
1. Turn on API Gateway execution logging
We enable execution logs on the stage, which are separate from access logs, and read the message for the failing request. 'Malformed Lambda proxy response' and 'Execution failed due to configuration error' point to different fixes.
2. Check the Lambda response shape
A proxy integration expects an object with statusCode as an integer, headers as an object, body as a string and optionally isBase64Encoded. Returning an object as body, or a bare value, causes the malformed error.
3. Check whether the function threw an error
If the function raised an unhandled exception, timed out or ran out of memory, API Gateway sees a failure rather than a response. We read the Lambda logs for the same request ID.
4. Check size and encoding
Responses over the Lambda synchronous payload limit fail, and binary content needs isBase64Encoded plus binary media types configured on a REST API. We reduce or redirect large payloads, for example to a pre-signed S3 URL.
5. Check permissions
API Gateway needs permission to invoke the function. A missing resource policy gives a configuration error; we add it by infrastructure as code and check the correct alias or version ARN.
6. Add a safe error wrapper and verify
We wrap the handler so every path returns a valid response with the right status code, then test through the API with good, bad and large inputs and add an alarm on 5XXError.
Mistakes we help you avoid
Common ways this goes wrong, and what we do instead.
Returning JSON object as body
Body must be a string. Use JSON.stringify or json.dumps.
Testing only in the Lambda console
The console does not use proxy event and response handling, so malformed responses go unnoticed.
Treating all 502 as timeouts
A timeout usually shows as 504. 502 is nearly always format or function failure.
Leaving execution logging off
Without it you are guessing.
Frequently Asked Questions
What does 'Malformed Lambda proxy response' mean?
API Gateway received something from Lambda that does not match the required proxy format, most often a body that is not a string or a missing statusCode.
Is a Lambda timeout a 502 or a 504?
The synchronous integration timeout normally returns 504. A function error or bad response returns 502. We read both logs to be sure.
Does the HTTP API behave the same?
Mostly, but HTTP APIs with payload format 2.0 can infer a response from a plain object. The format version matters, so we check which one you use.
Want Help With Fixing API Gateway 502 Bad Gateway with Lambda proxy?
Schedule an appointment. Tell us about your environment and we will outline the safest, highest-value approach.
Schedule Appointment › No commitment required