How can I troubleshoot 5xx errors for API Gateway?

5 minute read

When I call my Amazon API Gateway API, I get an 5xx error.

Short description

HTTP 5xx response codes indicate server errors. API Gateway 5xx errors include the following cases:

  • 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.

Use the CloudWatch logs to find 5xx errors from API Gateway. The API Gateway metric 5XXError counts the number of server-side errors that are 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 can occur because of any of the following scenarios:

  • Errors in the AWS Lambda function code
  • Missing permissions for using a stage variable
  • Incorrect or missing HTTP status code mapping
  • Throttling issues
  • Undefined HTTP method of POST
  • Lambda permissions
  • Lambda function JSON format issue
  • Backend payload size exceeding 10 MB
  • Private endpoint integration
  • Internal service failures

Errors in the Lambda function code

API endpoint 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 use a stage variable to set up an API Gateway to invoke a Lambda function, then you might receive an Internal server error. To resolve this error, see I defined my Lambda integration in API Gateway using a stage variable. 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 issue, set up mock integrations in API Gateway.

Throttling issues

If a high number of requests is throttling the backend service, then the API Gateway API might return an Internal server error. To resolve this issue, activate an exponential backoff and retry mechanism, and then try the request again. If the issue persists, then check your API Gateway quota limit. If you exceed the service quota limit, then you can request a quota increase.

Undefined HTTP method of POST

For Lambda integration, you must use the HTTP method of POST for the integration request.

Run the AWS CLI command put-integration to update the method integration request:

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, use the AWS CLI command create-deployment to deploy the REST API:

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name <value>

Lambda permissions

Make sure that the integrated Lambda function's or Lambda authorizer's 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 in JSON format:


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

Backend payload size exceeding 10 MB

The maximum backend payload size is 10 MB. You can't increase the size. Make sure that the backend payload size doesn't exceed the 10 MB default quota.

Private endpoint integration

If you're using a private API endpoint, you must also configure API Gateway private integration. Follow the instructions to set up API Gateway private integrations.

Internal service failures

If AWS experiences internal service problems, then you might receive a 500 error. Wait for the issue to resolve within AWS or the API Gateway service, and then retry the request with exponential backoff.

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 can't process the response as a gateway or proxy.

To troubleshoot this issue, see How do I resolve HTTP 502 errors from API Gateway REST APIs with Lambda proxy integration?

Note: When API Gateway interprets the response from the backend service, it uses mapping templates to map the format in the integration response section. 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 if the API Gateway API can't receive a response.

This error might occur in the following scenarios:

  • The backend server is overloaded beyond capacity and can't 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?

Related information

Security best practices in Amazon API Gateway

Monitoring REST API execution with Amazon CloudWatch metrics

AWS OFFICIALUpdated a year ago

This did not solve my problem. I'm getting an error 500 on an HTTP API, so I cannot enable execution logging, and none of the troubleshooting steps apply in my case. Please provide some sort of error reporting / logging for HTTP APIs, it's extremely frustrating to get an error 500 with no explanation of why.

replied 6 months ago

I discovered that my error 500 was caused by using an HTTP integration that referred to a host that only supports IPv6. API Gateway only supports IPv4, so this failed with a 500 error.

replied 6 months ago

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

profile pictureAWS
replied 6 months ago