Common DynamoDB Errors
(and Solutions)

DynamoDB error codes and what they mean

The exception name tells you more than the HTTP status. DynamoDB uses HTTP 400 for both invalid requests and transient conditions such as throttling. HTTP 500 and 503 indicate service-side failures.

HTTP 5xx: service errors and uncertain writes

InternalServerError and ServiceUnavailable are generally retryable with backoff. A failed write response does not prove that the write failed: the service may have applied it before the response was lost. Reconcile the item's state or use an idempotent operation before retrying a counter increment or another write that could be applied twice.

HTTP 400: inspect the exception before retrying

• AccessDeniedException: check the caller's IAM permissions, resource and endpoint policies, and request signing. Retrying an unchanged denied request will not grant access.
• IncompleteSignatureException: the request signature is missing required components. Use the SDK's signing support and check credentials.
• ResourceNotFoundException: check the table or index name, account, Region and endpoint. After creation, wait for the resource to become available before issuing data requests.
• ValidationException: fix the parameters, expression syntax, key types or unsupported option identified in the message.
• ConditionalCheckFailedException: a condition evaluated to false. Handle it as an application outcome, such as a version conflict or an item that already exists, rather than blindly retrying.
• LimitExceededException: too many concurrent control-plane operations or another operation-specific limit. Wait for ongoing operations to finish and retry with backoff; inspect the message for the limit that applies.
• ProvisionedThroughputExceededException, ThrottlingException and RequestLimitExceeded: a table, index, partition or configured quota cannot serve the request rate. Retry with backoff and diagnose the throttling reason below.
• TransactionCanceledException: the transaction was canceled. Inspect cancellation reasons in request order. Conflicts or throttling may be transient; failed conditions and invalid parameters require application handling. See transaction examples.
• TransactionConflictException or ReplicatedWriteConflictException: another write conflicts with this operation. Retry with backoff, while preserving any application conditions that protect correctness.

Read ThrottlingReasons to find the bottleneck

Current SDKs expose ThrottlingReasons, containing a reason and the affected resource ARN. The reason combines Table or Index, Read or Write, and one of these limit types:

• ProvisionedThroughputExceeded: configured provisioned capacity.
• AccountLimitExceeded: the on-demand table or index throughput service quota.
• KeyRangeThroughputExceeded: partition-level throughput, often a hot key.
• MaxOnDemandThroughputExceeded: the maximum throughput you configured.

For example, IndexWriteProvisionedThroughputExceeded points to a GSI write-capacity bottleneck that can throttle writes to its base table. Match the ARN to CloudWatch metrics before changing capacity. The throttling guide covers remediation; AWS documents the fields in the ThrottlingReason reference.

Handle retries and partial failures

AWS SDKs retry eligible transient failures with backoff, subject to their configured retry mode, attempt limit and retry budget. Catch errors after those attempts finish. Set a timeout appropriate for your application, log the exception name and request ID, and avoid stacking an unbounded retry loop around the SDK.

1. Fix validation and authorization failures before retrying. Treat a failed condition as a business decision or concurrency conflict.
2. For throttling, inspect ThrottlingReasons and the resource ARN. Sustained hot-key traffic, insufficient capacity or a configured on-demand cap needs remediation beyond retries.
3. Check successful batch responses too. BatchWriteItem can return UnprocessedItems and BatchGetItem can return UnprocessedKeys with HTTP 200. Retry only that subset with exponential backoff and jitter, within a bounded deadline.
4. Make retries safe. A repeated atomic increment can increment twice. Use conditional writes where appropriate, or reuse the same ClientRequestToken for an identical TransactWriteItems request within its idempotency window.

JavaScript SDK v3 supports client options such as maxAttempts; other SDKs have their own configuration APIs. Consult the AWS SDK retry settings and DynamoDB error-handling reference for the behavior of your SDK. The batch operations guide includes partial-failure handling.