Amazon API Gateway REST API Reference

Handling Errors in Amazon API Gateway

When you send requests to and get responses from the Amazon API Gateway API, you might encounter two types of API errors:

For each API error, Amazon API Gateway returns the following values:

For a list of error codes that Amazon API Gateway returns for client and server errors, see API Error Codes (Client and Server Errors).

Error Codes (Client and Server Errors)

HTTP status codes indicate whether an operation is successful or not.

A response code of 2xx indicates the operation was successful. Other error codes indicate either a client error (4xx) or a server error (5xx).

The following table lists the errors returned by Amazon API Gateway. Some errors are resolved if you simply retry the same request. The table indicates which errors are likely to be resolved with successive retries. If the value of the Retry column is:

For more information about retrying requests, see Error Retries and Exponential Backoff.

HTTP Status Code Error code Retry
400 Bad Request Exception No
403 Access Denied Exception No
404 Not Found Exception No
409 Conflict Exception No
429 Limit Exceeded Exception No
429 Too Many Requests Exception Yes
502 Bad Gateway Exception, usually for an incompatible output returned from a Lambda proxy integration backend and occasionally for out-of-order invocations due to heavy loads. Yes if idempotent
503 Service Unavailable Exception Yes
504 Endpoint Request Timed-out Exception Yes if idempotent

Sample Error Response

The following is an HTTP response indicating that the value for inputBucket was null, which is not a valid value.

HTTP/1.1 400 Bad Request
x-amzn-RequestId: b0e91dc8-3807-11e2-83c6-5912bf8ad066
x-amzn-ErrorType: ValidationException
Content-Type: application/json
Content-Length: 124
Date: Mon, 26 Nov 2012 20:27:25 GMT

{"message":"1 validation error detected: Value null at 'InstallS3Bucket' failed to satisfy constraint: Member must not be null"}

Catching Errors

For your application to run smoothly, you need to build in logic to catch and respond to errors. One typical approach is to implement your request within a try block or if-then statement.

The AWS SDKs perform their own retries and error checking. If you encounter an error while using one of the AWS SDKs, you should see the error code and description. You should also see a Request ID value. The Request ID value can help troubleshoot problems with Amazon API Gateway support.

Error Retries and Exponential Backoff

Numerous components on a network, such as DNS servers, switches, load balancers, and others can generate errors anywhere in the life of a given request.

The usual technique for dealing with these error responses in a networked environment is to implement retries in the client application. This technique increases the reliability of the application and reduces operational costs for the developer.

Each AWS SDK supporting Amazon API Gateway implements automatic retry logic. The AWS SDK for Java automatically retries requests, and you can configure the retry settings using the ClientConfiguration class. For example, in some cases, such as a web page making a request with minimal latency and no retries, you might want to turn off the retry logic. Use the ClientConfiguration class and provide a maxErrorRetry value of 0 to turn off the retries.

If you're not using an AWS SDK, you should retry original requests that receive server errors (5xx). However, client errors (4xx, other than a TooManyRequestsException) indicate you need to revise the request itself to correct the problem before trying again.

In addition to simple retries, we recommend using an exponential backoff algorithm for better flow control. The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. For example, you might let one second elapse before the first retry, four seconds before the second retry, 16 seconds before the third retry, and so on. However, if the request has not succeeded after a minute, the problem might be a hard limit and not the request rate. For example, you may have reached the maximum number of pipelines allowed. Set the maximum number of retries to stop around one minute.