How can I troubleshoot 5xx errors for API Gateway?
When I call my Amazon API Gateway API, I get an 5xx error. How do I troubleshoot API Gateway 5xx errors?
Short description
HTTP 5xx response codes indicate server errors. API Gateway 5xx errors include:
-
500 internal server
-
502 bad gateway
-
503 service unavailable
-
504 endpoint request timed out
Resolution
Before you begin, follow the steps to turn on Amazon CloudWatch Logs for troubleshooting API Gateway errors.
You can use the Amazon CloudWatch Logs to find 5xx errors from API Gateway. The API Gateway metric 5XXError counts the number of server-side errors captured in a given period.
Note:
If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.
500 error: internal server error
This error might be due to:
-
Errors in the AWS Lambda function code.
-
Missing permissions for using a stage variable.
-
Incorrect or missing HTTP status code mapping.
-
Throttling issues.
-
The HTTP method of POST isn't defined.
-
Lambda permissions.
-
Lambda function JSON format issue.
-
The backend payload size exceeded 10 MB.
-
Private endpoint integration.
Errors in the Lambda function code
API endpoints 500 errors that integrate with Lambda might indicate that the Lambda function has an error in the code. For more information and troubleshooting, see Error handling patterns in Amazon API Gateway and AWS Lambda.
Missing permissions for using a stage variable
If you set up an API Gateway to invoke an AWS Lambda function using a stage variable, you might receive an "internal server error". To resolve this error, see Why do I get an "Internal server error" and a 500 status code when I invoke the API method?
Incorrect or missing HTTP status code mapping
Incorrect or missing HTTP status code mapping can also result in 500 errors. To resolve this error, you can Set up mock integrations in API Gateway.
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.
The HTTP method of POST isn't defined
For Lambda integration, you must use the HTTP method of POST for the integration request.
Update the method integration request using the AWS CLI command put-integration similar to the following:
aws apigateway put-integration \
--rest-api-id id \
--resource-id id \
--http-method ANY \
--type AWS_PROXY \
--integration-http-method POST \
--uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations
Then, deploy the REST API using the AWS CLI command create-deployment similar to the following:
aws apigateway create-deployment \
--rest-api-id id \
--stage-name <value>
Lambda permissions
Make sure that the integrated Lambda function or Lambda authorizers resource-based policy includes permissions for your API to invoke the function. Follow the instructions to update your Lambda function's resource-based policy.
Lambda function JSON format issue
The integrated Lambda function isn't returning output according to the predefined JSON format for REST APIs and HTTP APIs. Update your Lambda function or Lambda authorizer function JASON format similar to the following:
REST API
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headerName": "headerValue", ... },
"multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
"body": "..."
}
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": { "headername": "headervalue", ... },
"multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
"body": "..."
}
The backend payload size exceeded 10 MB
The maximum backend payload size is 10 MB and can't be increased. Make sure that the backend payload size doesn't exceed the 10 MB default quota.
Private endpoint integration
If you are using a private API endpoint, you must also configure API Gateway private integration. Follow the instructions to Set up API Gateway private integrations.
502 error: bad gateway
A 502 error code is related to the AWS service that your API Gateway integrates with such as an AWS Lambda function. API Gateway couldn’t process the response as a gateway or proxy.
To troubleshoot 502 error when integrated with a Lambda proxy function, see How do I resolve HTTP 502 errors from API Gateway REST APIs with Lambda proxy integration?
Note:
API Gateway interprets the response from the backend service in a format that can be mapped in the integration response section using mapping templates. For more information, see Set up an integration response in API Gateway.
503 error: service unavailable
A 503 error code is related to the backend integration and the API Gateway API is unable to receive a response.
This error might occur if the backend server is:
-
Overloaded beyond capacity and is unable to process new client requests.
-
The backend server is under temporary maintenance.
To resolve this error, consider provisioning more resources to the backend server and activating an exponential backoff and retry mechanism on the client. Then, try the request again.
504 error: endpoint request timed out
If an integration request takes longer than your API Gateway REST API maximum integration timeout parameter, API Gateway returns an HTTP 504 status code.
To resolve this error, see How can I troubleshoot API HTTP 504 timeout errors with API Gateway?
Security best practices in Amazon API Gateway
Monitoring REST API execution with Amazon CloudWatch metrics
Submit feedback
Do you need billing or technical support?
Contact AWS Support