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

Short description

This error might be due to:

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

Resolution

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?