API Error Retries

REST client errors are indicated by a 4xx HTTP response code.

Do not retry client errors. Client errors indicate that Amazon SimpleDB found a problem with the client request and the application should address the issue before submitting the request again.

For server errors, you should retry the original request.

REST server errors are indicated by a 5xx HTTP response code.

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.

You should retry original requests that receive server errors (5xx). However, client errors (4xx) 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 concept behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. For example, up to 400 milliseconds before the first retry, up to 1600 milliseconds before the second, up to 6400 milliseconds before third, and so on.

Following is a workflow showing retry logic. The workflow logic first determines if the error is a server error (5xx). Then, if the error is a server error, the code retries the original request.

currentRetry = 0
DO
  execute Amazon SimpleDB request
  IF status = success
    set retry to false
  ELSE IF status = server error (5xx)
    set retry to true
    currentRetry = currentRetry + 1
    wait for a random delay between 0 and (4^currentRetry * 100) milliseconds
  ELSE
    set retry to false and fix client error (4xx)
WHILE (retry = true AND currentRetry < MaxNumberOfRetries)  // limit retries

Following is a snippet of Java code that implements the logic and exponential backoff.

 boolean shouldRetry = true;
 int retries = 0;
 do {
   try {
    /* Submit request to Amazon SimpleDB*/
     if (status == HttpStatus.SC_OK) {
       shouldRetry = false;
      /* Process successful response from Amazon SimpleDB */
     } else {
       if (status == HttpStatus.SC_INTERNAL_SERVER_ERROR
	      || status == HttpStatus.SC_SERVICE_UNAVAILABLE) {
	 shouldRetry = true;
	 long delay = (long) (Math.random() * (Math.pow(4, retries++) * 100L));
	 try {
	   Thread.sleep(delay);
	 } catch (InterruptedException iex){
	   log.error("Caught InterruptedException exception", iex);
	 }
       } else {
	 shouldRetry = false;
	/* Process 4xx (Client) error */
       }
     }
   } catch (IOException ioe) {
     log.error("Caught IOException exception", ioe);
   } catch (Exception e) {
     log.error("Caught Exception", e);
   } finally {
     /* Perform clean-up as necessary */
   }
 } while (shouldRetry && retries < MAX_NUMBER_OF_RETRIES);

The AWS SDKs that support Amazon SimpleDB implement retries and exponential backoff. For example, to download Java code that implements the exponential backoff algorithm, see the AWS SDK for Java.