How do I resolve HTTP 502 errors from API Gateway REST APIs with Lambda proxy integration?

Short description

If your Lambda function's permissions are incorrect or the response to the API request isn't formatted correctly, then API Gateway returns an HTTP 502 status code.

Example HTTP 502 error messages as it appears in Amazon CloudWatch Logs

Wed Aug 03 08:10:00 UTC 2022 : Execution failed due to configuration error: 
WE Aug 03 09:10:00 UTC 2022 : Method completed with status: 502

-or-

Wed Aug 03 08:20:33 UTC 2022 : Lambda execution failed with status 200 due to customer function error: [Errno 13] Permission denied: '/var/task/lambda_function.py'. Lambda request id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Wed Aug 03 08:20:33 UTC 2022 : Method completed with status: 502

For API Gateway to handle a Lambda function's response, the function must return output according to the following JSON format:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "body": "..."
}

For more information, see Output format of a Lambda function for proxy integration.

Resolution

1.    Review your REST API's CloudWatch metrics with the API dashboard in API Gateway.
-or-
Review your REST API's log events in the Amazon CloudWatch console.

2.    In the logs, review the format of your Lambda function's response to your API. If the response isn't in the required JSON format, then reformat it.

3.    Verify that the Lambda function's resource policy allows access to invoke the function with API Gateway.

4. If the Lambda function execution fails due to a package permission issue, then verify the permissions. For instructions, see How do I troubleshoot "permission denied" or "unable to import module" errors when uploading a Lambda deployment package?

5.    Verify that the Lambda function handler name and configuration are valid.

6.    If the Lambda execution fails during runtime, check the Lambda function logs and update the code.

7.    After making your changes, you can test your REST API method in the API Gateway console.

Example Node.js Lambda function with the response correctly formatted

Note: Node.js Lambda functions support async handlers and non-async handlers. The following example function uses an async handler.

exports.handler = async (event) => {

    const responseBody = {
        "key3": "value3",
        "key2": "value2",
        "key1": "value1"
    };

    const response = {
        "statusCode": 200,
        "headers": {
            "my_header": "my_value"
        },
        "body": JSON.stringify(responseBody),
        "isBase64Encoded": false
    };

    return response;
};

In this example response, there are four fields:

• statusCode is an integer interpreted by API Gateway that's returned to the caller of the API method.
• headers are collected and then sent back with the API Gateway response.
• body must be converted to a string if you're returning data as JSON.
  Note: You can use JSON.stringify to handle this in Node.js functions. Other runtimes require different solutions, but the concept is the same.
• isBase64Encoded is a required field if you're working with binary data. If you don't use this field, it's a best practice to set the value to FALSE.

Related information

Setting up CloudWatch logging for a REST API in API Gateway Monitoring REST APIs with Amazon CloudWatch metrics