AWS API Gateway 502 Malformed Lambda Proxy Response — What It Means & How to Fix It

Fix AWS API Gateway 502 Internal Server Error caused by Lambda returning a response that does not match the expected proxy integration format. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: API Gateway expects Lambda proxy integrations to return a specific JSON format with statusCode, headers, and body. A 502 occurs when the Lambda response does not match this expected format. Common issues include returning a raw string, missing statusCode, or body not being a string. This error appears as 'Malformed Lambda proxy response' in CloudWatch Logs. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Lambda function returning an object without statusCode, headers, or body properties. Body field containing a JSON object instead of a JSON string (must use JSON.stringify). Lambda function timing out before returning a response. Unhandled exception in Lambda causing it to crash without returning a valid response. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Ensure Lambda returns: { statusCode: 200, headers: {}, body: JSON.stringify(data) }. Check CloudWatch Logs for the Lambda function to see the actual error or response format. Add try-catch around the handler to always return a valid response even on errors. Test the Lambda function directly in the AWS console with a test event to verify the response format. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.