Handling Errors

While interacting with Amazon DynamoDB programmatically, you might encounter errors of two types: client errors and server errors. Each error has a status code (such as 400), an error code (such as ValidationException), and an error message (such as Supplied AttributeValue is empty, must contain exactly one of the supported datatypes).

HTTP status codes indicate whether an operation is successful or not. There are two types of error codes, client (4xx) and server (5xx).

A response code of 200 indicates the operation was successful.

The following table lists the errors returned by Amazon DynamoDB. 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 Retry column contains a "Y", submit the same request again. If the Retry column contains an "N", fix the problem on the client side before submitting a new request. For more information about retrying requests, see Error Retries and Exponential Backoff.

HTTP/1.1 400 Bad Request
x-amzn-RequestId: LDM6CJP8RMQ1FHKSC1RBVJFPNVV4KQNSO5AEMF66Q9ASUAAJG
Content-Type: application/x-amz-json-1.0
Content-Length: 240
Date: Thu, 15 Mar 2012 23:56:23 GMT

{"__type":"com.amazonaws.dynamodb.v20111205#ProvisionedThroughputExceededException",
"message":"The level of configured provisioned throughput for the table was exceeded. 
Consider increasing your provisioning level with the UpdateTable API"}

For your application to run smoothly, you need to build logic into the application 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 DynamoDB support.

The following example uses the AWS SDK for Java to delete an item within a try block and uses a catch block to respond to the error (in this case, it warns the user that the request failed). The example uses the AmazonServiceException class to retrieve information about any operation errors, including the Request ID. The example also uses the AmazonClientException class in case the request is not successful for other reasons.

try {
    DeleteItemRequest request = new DeleteItemRequest(tableName, key);
    DeleteItemResult result = dynamoDB.deleteItem(request);
    System.out.println("Result: " + result);    	
    // Get error information from the service while trying to run the operation	
	}   catch (AmazonServiceException ase) {
		System.err.println("Failed to delete item in " + tableName);
        // Get specific error information
        System.out.println("Error Message:    " + ase.getMessage());
        System.out.println("HTTP Status Code: " + ase.getStatusCode());
        System.out.println("AWS Error Code:   " + ase.getErrorCode());
        System.out.println("Error Type:       " + ase.getErrorType());
        System.out.println("Request ID:       " + ase.getRequestId());
    // Get information in case the operation is not successful for other reasons	
    } catch (AmazonClientException ace) {
        System.out.println("Caught an AmazonClientException, which means"+
        " the client encountered " +
        "an internal error while trying to " +
         "communicate with Amazon DynamoDB, " +
        "such as not being able to access the network.");
        System.out.println("Error Message: " + ace.getMessage());
    }

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 DynamoDB implements retry logic, automatically. 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. For more information, see Using the AWS SDKs with Amazon DynamoDB.

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 ThrottlingException or a ProvisionedThroughputExceededException) 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 50 milliseconds before the first retry, up to 100 milliseconds before the second, up to 200 milliseconds before third, and so on. However, after a minute, if the request has not succeeded, the problem might be the request size exceeding your provisioned throughput, and not the request rate. Set the maximum number of retries to stop around one minute. If the request is not successful, investigate your provisioned throughput options. For more information, see Guidelines for Working With Tables.

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
  set retry to false

  execute Amazon DynamoDB request

  IF Exception.errorCode = ProvisionedThroughputExceededException
    set retry to true
  ELSE IF Exception.httpStatusCode = 500
    set retry to true
  ELSE IF Exception.httpStatusCode = 400
    set retry to false 
    fix client error (4xx)

  IF retry = true  
    wait for (2^currentRetry * 50) milliseconds
    currentRetry = currentRetry + 1

WHILE (retry = true AND currentRetry < MaxNumberOfRetries)  // limit retries