Handling Lambda errors with an API Gateway API

API Gateway treats all invocation and function errors as internal errors. If the Lambda API rejects the invocation request, API Gateway returns a 500 error code. If the function runs but returns an error, or returns a response in the wrong format, API Gateway returns a 502. In both cases, the body of the response from API Gateway is {"message": "Internal server error"}.

The following example shows an X-Ray trace map for a request that resulted in a function error and a 502 from API Gateway. The client receives the generic error message.

To customize the error response, you must catch errors in your code and format a response in the required format.

var formatError = function(error){
 var response = {
 "statusCode": error.statusCode,
 "headers": {
 "Content-Type": "text/plain",
 "x-amzn-ErrorType": error.code
 },
 "isBase64Encoded": false,
 "body": error.code + ": " + error.message
 }
 return response
}

API Gateway converts this response into an HTTP error with a custom status code and body. In the trace map, the function node is green because it handled the error.

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.