How Does API Gateway Handle the Response Returned by a Lambda Function?

Question

When I invoke my HTTP API on API Gateway, it forwards the request to my Lambda function, which executes and returns a response. What exactly does API Gateway do with this response? Does it pass it directly to the client, or does it perform any transformation or additional configuration? How can I customize this behavior (such as headers, status codes, and response

MikeLim · Accepted Answer

```
How can I customize this behavior (such as headers, status codes, and response...
```

To add to re:Post agent reply, you need to return a JSON response. Specify headers, code and body in your returned JSON response. Below is an example in Python

```
def lambda_handler(event, context):  
  return {
    'statusCode': 200,
    'body': "hello",
    "headers": {
      "content-type": "application/json",
      "Strict-Transport-Security": "max-age=31536000"
      }
    }
```

Refer to [documentation: Create AWS Lambda proxy integrations for HTTP APIs in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html#http-api-develop-integrations-lambda.response) for details.

re:Post Agent · Answer

API Gateway handles the response returned by a Lambda function in the following way:

1. Serialization: When the Lambda function completes its execution, it returns a response object. The Lambda runtime serializes this response object into JSON format.

2. Parsing: API Gateway receives the serialized JSON response from the Lambda function and parses it.

3. HTTP Response Creation: Using the parsed response, API Gateway constructs an HTTP response. This includes setting the appropriate status code, headers, and body.

4. Client Delivery: The constructed HTTP response is then sent back to the client that made the original request.

For Lambda proxy integrations, API Gateway automatically handles the backend output without requiring additional configuration. The Lambda function must return its result in a specific JSON format that includes:

- isBase64Encoded (boolean)
- statusCode (number)
- headers (object)
- body (JSON string)

API Gateway uses this structure to create the HTTP response. The statusCode determines the HTTP status code, headers are set as response headers, and the body becomes the response payload.

For non-proxy (custom) integrations, you have more control over how the Lambda response is handled:

1. You can set up integration responses to pass the Lambda function response through as-is to the corresponding method response.

2. Alternatively, you can map the Lambda response data to the method response data. This allows you to transform the status code, response headers, and body.

3. If no method response is defined for the returned status code, API Gateway will return a 500 error.

To customize the behavior:

1. Headers: You can add or modify headers in your Lambda function response. For proxy integrations, include them in the headers object of the response.

2. Status Codes: Set the desired status code in the statusCode field of your Lambda response for proxy integrations. For custom integrations, you can map different Lambda responses to different HTTP status codes using integration responses.

3. Response Body: You have full control over the response body in your Lambda function. For proxy integrations, return it in the body field of the response object.

4. Error Handling: For custom integrations, you need to map Lambda errors to appropriate HTTP responses. For proxy integrations, use the statusCode to indicate errors (e.g., 4XX for client errors, 5XX for server errors).

5. CORS: If needed, ensure your Lambda function includes the necessary CORS headers in its response.

By leveraging these options, you can fine-tune how API Gateway processes and returns the Lambda function's response to meet your specific API requirements.  
**Sources**  
[Lambda proxy integrations in API Gateway - Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html)  
[Set up an integration response in API Gateway - Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-integration-settings-integration-response.html)  
[Invoking a Lambda function using an Amazon API Gateway endpoint - AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/services-apigateway.html)  
[Handle Lambda errors in API Gateway - Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/handle-errors-in-lambda-integration.html)

How Does API Gateway Handle the Response Returned by a Lambda Function?

Add your answer

Relevant content