Amazon API Gateway HTTP Errors

Amazon API Gateway is a fully managed service that helps developers to create and deploy scalable APIs on AWS. These APIs act as an entry point for the applications to connect and get access to data, perform business logic or access any other AWS service.

Amazon API Gateway also returns some HTTP Errors and we will be discussing some of the errors in this blog post and what they mean when returned from the Amazon API Gateway. Usually, the errors returned are in the range of 4xx or 5xx and examples for the same are 400 or 500. As a rule of thumb errors in the range of 400-499 are usually returned if there are problems with the client or you are breaking some of the rules defined by the Amazon API Gateway.

The errors in the range of 500-599 mean the server is not working problem or you have an issue with the network or the issues in the infrastructure which runs your server.

400 Error: Bad Request

The HTTP Status 400: Bad Request is the broadest error and depending on what AWS service API Gateway is integrating with, this error means many things. Some of the reasons for this error can be an invalid JSON, wrong data types and required fields etc.

403 Error: Access Denied

The HTTP Status 403: Forbidden means there are some permission issues. In AWS, this can be an issue with a wrong IAM role configuration. If your service uses an auth mechanism like AWS Cognito or a custom authorizer, this can be a permission issue because of this, then this error code will be returned.

404 Error: Not Found

The HTTP Status 404: This means the resource is not available or the URL does not exist. You can check the URL if it is right or not or have been implemented right to make sure that you are not making any mistake.

409 Error: Conflict

The HTTP Status 409: indicates that your request is trying to do something that conflicts with the current state of the target resource. It is most likely to occur in response to a PUT request.

429 Error: Too Many Requests

There are two cases when you can receive 429 errors from API Gateway.

The first one for HTTP Status 429: \”Too Many Request\”. This usually happens when the downstream resource is not able to handle the number of requests coming in.

For example, if you have a Lambda which gets triggered via an API Gateway and there is a reserved concurrency assigned to it let\’s say 20 then 21 requests will same time probably give you this error.

This can also happen if your API keys are not allowing more than x number of requests concurrently. If the number of requests exceeds the number even if the downstream resource can handle it, the API Gateway will give this error.

429 Error: Limit Exceeded

The second one for HTTP Status 429 is “Limit Exceeded Exception,” which means that youhave exceeded the allowed number of requests. This happens when the request is metered using an API key in API Gateway. The usage plan is associated with the key and the plan decides how many requests are allowed in a month by that particular resource.

500 Error: Internal Server Error

HTTP Status 500: It is the most generic HTTP error you will see. If the downstream service is Lambda, this error can mean an issue or a bug in the code of the function.

This can also happen if the status code mapping in the API is wrong. The default mapping if the error mapping is not configured properly, then the status code returned to the client is HTTP Status code 500.

502 Error: Bad Gateway

HTTP Status 502: this usually happens when the downstream service is not able to provide a response that can be mapped easily with the API Gateway. Sometimes the downstream service is not ready and cannot return a response.

503 Error: Service Unavailable

Amazon API Gateway has a hard limit of 30 seconds timeouts. If the downstream service is not able to respond in this time frame, the API Gateway returns the HTTP Status 503.


The above-mentioned codes are some of the common errors which you may encounter while working with the Amazon API Gateway. If you would like to be familiar with the other things related to Amazon API Gateway, we have a collection that lists all the articles related to it. You can find it here.