AWS Lambda proxy integration in API Gateway illustrated

Here is a short story to illustrate how requests go through API Gateway using AWS Lambda (with the Lambda Proxy Integration).
The story is divided in 4 parts:

1) The big picture (no error)
2) In case of an error in the code of the Lambda
3) In case of an error with the AWS Lambda service
4) Lambda code error handling example

In this story I am only speaking about the specific “Lambda Proxy integration” in API Gateway

The Lambda Proxy integration in Amazon API Gateway

1) The big picture (no error)

HTTP typical request and response flow using Lambda proxy integration

Informations (such as http path, http methods, http body, …) of the client’s request are passed as an argument to the Lambda function.

Based on specific return values of your Lambda function, the API Gateway will return specific HTTP codes, HTTP headers and HTTP body.

With AWS Lambda proxy integrations, you are crafting the whole HTTP response for the client inside you AWS Lambda function

In case of an error in the code

HTTP request and response flow (with error in the code of the Lambda)

If there is an error in your code and you do not catch this error in the code, then the AWS Lambda service will return a 200 HTTP response but with a specific header in it: “X-Amz-Function-Error”.
The 200 code means AWS Lambda was able to invoke the function.
The “X-Amz-Function-Error” is there to show an error occurred in the code.

API Gateway will then return a 5XX HTTP response to the client with a generic error message (“internal server error”) in the body.

Example of code errors:

• Code timeout
• Syntax error
• …

In case of an error with the AWS Lambda service

Invocation error

In some cases, API Gateway won’t even be able to trigger the Lambda function, it is called an invocation error.

Invocation error examples:

• Invalid request (payload too large ?)
• Too many requests ? (1000 concurrent run limit for Lambda)
• …

In that case, API Gateway will receive an error 4XX or 5XX from the Lambda service.
The client will then receive an error 5XX from API Gateway with an internal server error message as the body of the response.

4) Lambda code error handling example

This is an example of how to manage errors inside your Lambda function

Lambda errors handling example in Python

By default an error is returned in the snippet above. The code has to manually change the body and response code in case of a success.

The end

That’s it for this post.
If you spot any error, simply reach out to me.