How do I troubleshoot issues for API Gateway endpoints that integrate with Lambda?

Resolution

Follow these troubleshooting steps for the error that you received.

Before you begin, turn on Amazon CloudWatch Logs to troubleshoot API Gateway errors. For Log level, choose INFO to generate execution logs for all requests.

API Gateway doesn't have Lambda function permissions

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

Note: If you use another service to deploy your API Gateway resources, such as AWS CloudFormation, then grant permissions to the AWS::Lambda::Permission resource.

Throttling occurs

If the backend service throttled because of a high number of requests, then the API Gateway API might return an Internal server error. Activate an exponential backoff and retry mechanism, and then send the request again. If the issue persists, then check your API Gateway quota. If you exceed the service quota, then request a quota increase for the concurrency of the Lambda function so that the function doesn't throttle.

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

The status code mapping is incorrect or missing

When the HTTP status code mapping is incorrect or missing, you can receive a 500 error message 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, configure the API operation's integration request and response to return the correct status code.

Lambda service exceptions aren't managed

If you don't manage Lambda service exceptions, such as a Lambda function timeout, then you receive a Lambda.Unknown error. To prevent a Lambda function timeout, make your Lambda function code idempotent.

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

Lambda integration endpoint timeout issues

The API Gateway integration timeout default quota limit is 29 seconds for all integration types. If your Lambda function takes more than 29 seconds to return the response, then the request fails with a 504 Endpoint request timed out error.

Make sure that your Lambda function returns the response within 29 seconds. If your Lambda function can't return the response within 29 seconds, then submit a quota increase for the integration timeout limit.

Note: You can increase the integration timeout to greater than 29 seconds for Regional APIs and private APIs. However, an integration timeout increase might require a reduction in your Region-level throttle quota for your AWS account.

Lambda function output JSON format incorrect

If the output from your integrated Lambda function doesn't conform to the specified JSON format for REST APIs, then you receive a malformed proxy error. Make sure to use the correct JSON format for the output from Lambda functions for proxy integrations and from Lambda authorizers.

Example Lambda function for proxy integration:

{

"isBase64Encoded": true|false,

"statusCode": httpStatusCode,

"headers": { "headerName": "headerValue", ... },

"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },

"body": "..."

}

Related information

How do I troubleshoot API Gateway HTTP invoke errors?