Last updated: 2022-09-22

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

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.

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": "..."
}

HTTP API

{
    "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.

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.

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.

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?