This section describes runtime errors and how to handle them. It also describes error messages and codes that are specific to Amazon DynamoDB. For a list of common errors that apply to all AWS services, seeAccess Management

Error components

When your program sends a request, DynamoDB attempts to process it. If the request is successful, DynamoDB returns an HTTP success status code (200 OK), along with the results from the requested operation.

If the request is unsuccessful, DynamoDB returns an error. Each error has three components:

The AWS SDKs take care of propagating errors to your application so that you can take appropriate action. For example, in a Java program, you can writetry-catch logic to handle aResourceNotFoundException.

If you are not using an AWS SDK, you need to parse the content of the low-level response from DynamoDB. The following is an example of such a response.

HTTP/1.1 400 Bad Requestx-amzn-RequestId: LDM6CJP8RMQ1FHKSC1RBVJFPNVV4KQNSO5AEMF66Q9ASUAAJGContent-Type: application/x-amz-json-1.0Content-Length: 240Date: Thu, 15 Mar 2012 23:56:23 GMT{"__type":"com.amazonaws.dynamodb.v20120810#ResourceNotFoundException","message":"Requested resource not found: Table:tablename not found"}

Transactional errors

For information on transactional errors, please seeTransaction conflict handling in DynamoDB

Error messages and codes

The following is a list of exceptions returned by DynamoDB, grouped by HTTP status code. IfOK to retry? isYes, you can submit the same request again. IfOK to retry? isNo, you need to fix the problem on the client side before you submit a new request.

HTTP status code 400

An HTTP400 status code indicates a problem with your request, such as authentication failure, missing required parameters, or exceeding a table's provisioned throughput. You have to fix the issue in your application before submitting the request again.

HTTP status code 5xx

An HTTP5xx status code indicates a problem that must be resolved by AWS. This might be a transient error, in which case you can retry your request until it succeeds. Otherwise, go to theAWS Service Health Dashboard to see if there are any operational issues with the service.

For more information, seeHow do I resolve HTTP 5xx errors in Amazon DynamoDB?

Error handling in your application

For your application to run smoothly, you need to add logic to catch and respond to errors. Typical approaches include usingtry-catch blocks orif-then statements.

The AWS SDKs perform their own retries and error checking. If you encounter an error while using one of the AWS SDKs, the error code and description can help you troubleshoot it.

You should also see aRequest ID in the response. TheRequest ID can be helpful if you need to work with AWS Support to diagnose an issue.

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.

Each AWS SDK implements retry logic automatically. You can modify the retry parameters to your needs. For example, consider a Java application that requires a fail-fast strategy, with no retries allowed in case of an error. With the AWS SDK for Java, you could use theClientConfiguration class and provide amaxErrorRetry value of0 to turn off the retries. For more information, see the AWS SDK documentation for your programming language.

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

In addition to simple retries, each AWS SDK implements 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.

Most exponential backoff algorithms use jitter (randomized delay) to prevent successive collisions. Because you aren't trying to avoid such collisions in these cases, you do not need to use this random number. However, if you use concurrent clients, jitter can help your requests succeed faster. For more information, see the blog post aboutExponential backoff and jitter.

Batch operations and error handling

The DynamoDB low-level API supports batch operations for reads and writes.BatchGetItem reads items from one or more tables, andBatchWriteItem puts or deletes items in one or more tables. These batch operations are implemented as wrappers around other non-batch DynamoDB operations. In other words,BatchGetItem invokesGetItem once for each item in the batch. Similarly,BatchWriteItem invokesDeleteItem orPutItem, as appropriate, for each item in the batch.

A batch operation can tolerate the failure of individual requests in the batch. For example, consider aBatchGetItem request to read five items. Even if some of the underlyingGetItem requests fail, this does not cause the entireBatchGetItem operation to fail. However, if all five read operations fail, then the entireBatchGetItem fails.

The batch operations return information about individual requests that fail so that you can diagnose the problem and retry the operation. ForBatchGetItem, the tables and primary keys in question are returned in theUnprocessedKeys value of the response. ForBatchWriteItem, similar information is returned inUnprocessedItems.

The most likely cause of a failed read or a failed write isthrottling. ForBatchGetItem, one or more of the tables in the batch request does not have enough provisioned read capacity to support the operation. ForBatchWriteItem, one or more of the tables does not have enough provisioned write capacity.

If DynamoDB returns any unprocessed items, you should retry the batch operation on those items. However,we strongly recommend that you use an exponential backoff algorithm. If you retry the batch operation immediately, the underlying read or write requests can still fail due to throttling on the individual tables. If you delay the batch operation using exponential backoff, the individual requests in the batch are much more likely to succeed.

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.