How can I troubleshoot the "internal server" error with status code 500 for API Gateway endpoints that integrate with Lambda?

3 minute read

I sent an HTTP request to my Amazon API Gateway API endpoint that integrates with AWS Lambda (for example, /lambda-resource GET). I received a status code 500 response with the following error: {"message": "Internal server error"} How can I troubleshoot this error?

Short description

This error might be due to:

  • Lambda function permissions
  • Throttling issues
  • Incorrect or missing HTTP status code mapping
  • Unhandled errors


Before you begin, follow the steps to turn on Amazon CloudWatch Logs for troubleshooting API Gateway errors.

Note: For Log level, choose INFO to generate execution logs for all requests.

Lambda function permissions

The error “Invalid permissions on Lambda function” occurs if API Gateway doesn't have permissions to invoke the Lambda function. To resolve this, see How do I resolve "Invalid permissions on Lambda function" errors from API Gateway REST APIs?

Note: If you used another service, such as AWS CloudFormation, to deploy your API Gateway resources, make sure that you have permissions to the AWS::Lambda::Permission resource.

Throttling issues

If the backend service is throttled due to a high number of requests, the API Gateway API might return an "Internal server error". You can activate an exponential backoff and retry mechanism and try the request again. If the issue persists, check your API Gateway quota limit. If you exceeded the service quota limit, you can request a quota increase.

You might also receive "Rate exceeded" and 429 "TooManyRequestsException" errors due to Lambda function throttling issues. For more information, see How do I troubleshoot Lambda function throttling with "Rate exceeded" and 429 "TooManyRequestsException" errors?

You can also request an increase for the Lambda function's concurrency limit so that the function doesn't get throttled. For instructions, see How do I request a concurrency limit increase for my Lambda function?

Incorrect or missing HTTP status code mapping

Incorrect or missing HTTP status code mapping can also result in 500 errors similar to the following:

"Execution failed due to configuration error: Output mapping refers to an invalid method response: 2xx/4xx/5xx".

To resolve this error, make sure that an API method response exists for the status code returned from the backend and is mapped correctly.

Unhandled errors

Unhandled errors in Lambda indicate that the function timeouts due to errors in the function code. To prevent this error, make sure that the Lambda function code is idempotent.

You can also use the debugging tool AWS X-Ray to get more details on how long different sections of your function’s code takes to complete.

For more information, see Error handling patterns in Amazon API Gateway and AWS Lambda.

Related information

How can I troubleshoot 5xx errors for API Gateway?

AWS OFFICIALUpdated 2 years ago

The underlying reason I was getting 500 with API Gateway v2 was malformed payload (HTTP status code mapping was correct in json). The quotes needed to be escaped in the json or the payload to be encoded in Base64. An example of valid payload would be '{ "isBase64Encoded": false, "statusCode": 200, "body": "{ "allo": "hehe" }" }'. More details in this article and AWS Custom Lambda returns status OK but API Gateway v2 fails with 500

replied 9 months ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
replied 9 months ago

Is it possible to map a throttling issue of an authorizer lambda (429 error in execution logs) to an ApiGateway response status code 429? Or does it in this case always return a 500 error to the client and there is no way to change that?

replied 5 months ago

Thank you for your comment. We'll review and update the Knowledge Center article as needed.

profile pictureAWS
replied 5 months ago