Amazon DynamoDB errors

Look up a DynamoDB exception by name — whether to retry it, what it means, and the fix — covering throttling (ProvisionedThroughputExceeded, Throttling, RequestLimitExceeded), conditional and validation failures, item-collection and control-plane limits, authentication, and 5xx with the rule for retrying writes.

markdownreferencev42HVP-R0RXstage: operatetrust: officialservice: dynamodbinterface: anyProvisionedThroughputExceededExceptionThrottlingExceptionRequestLimitExceededConditionalCheckFailedExceptionValidationExceptionItemCollectionSizeLimitExceededExceptionLimitExceededExceptionResourceNotFoundExceptionResourceInUseExceptionAccessDeniedException DynamoDBUnrecognizedClientExceptionMissingAuthenticationTokenExceptionReplicatedWriteConflictExceptionTransactionCanceledExceptionInternalServerErrorUnprocessedItems

Created 18 Oct 2026 · Modified 23 Oct 2026 · 4 versions

The SDKs already retry the retryable errors with exponential backoff. If one reaches your code, the rate is too high for the table or account, or the request itself is wrong. Never blindly retry a 4xx other than the throttling ones.

Exception (HTTP 400 unless noted)Retry?Meaning → fixCheck
ProvisionedThroughputExceededExceptionYes, slowerA provisioned table or GSI is over its throughput. Back off; raise capacity, switch to on-demand, or spread keysThrottledRequests and consumed vs provisioned capacity for the table and each GSI in CloudWatch at that minute; aws dynamodb describe-table --table-name <t> → BillingModeSummary
ThrottlingExceptionYes, slowerThe request rate is too high: control-plane calls too fast, or a high on-demand data-plane rateWhich call failed: control-plane (CreateTable, UpdateTable, …) vs data-plane. CloudTrail errorCode for control-plane bursts
RequestLimitExceededYes, slowerThroughput exceeds the account limit; an on-demand table can't scale further. Request a quota increase (Service Quotas)aws dynamodb describe-limits against the account's consumed throughput; Service Quotas for the live account value
ConditionalCheckFailedExceptionNoYour ConditionExpression was false. That is the expected outcome of an optimistic or conditional write: handle it as business logicRead the item (get-item --consistent-read) and evaluate the ConditionExpression against it; add ReturnValuesOnConditionCheckFailure: ALL_OLD to see the item that failed
ValidationExceptionNoMalformed request: missing or out-of-range parameter, type mismatch, a reserved word not aliased, key schema mismatch, or a constraint exceeded (item over 400 KB, expression over 4 KB, more than 100 IN values, more than 100 transaction items)The message names the parameter. Compare the key attributes and types with describe-table → KeySchema/AttributeDefinitions
ItemCollectionSizeLimitExceededExceptionYes, after fixingA partition key's item collection passed 10 GB on a table with an LSI. Redesign keys (an LSI can't be removed)describe-table shows LocalSecondaryIndexes; the error only occurs on tables that have one
LimitExceededExceptionYesToo many concurrent control-plane operations: more than 500 tables and indexes in CREATING, DELETING or UPDATINGaws dynamodb list-tables + describe-table → TableStatus for tables in CREATING, UPDATING or DELETING
ResourceNotFoundExceptionNoWrong table name or Region, or the table is still too early in CREATING. Wait with aws dynamodb wait table-existsaws dynamodb describe-table --table-name <t> --region <r>: does it exist in this account and Region, and is TableStatus ACTIVE?
ResourceInUseExceptionNoCreating a table that exists, or deleting one still CREATINGdescribe-table → TableStatus
AccessDeniedExceptionNoThe request wasn't correctly signed (the error page's wording). Also the usual name for an IAM or KMS denial (UNVERIFIED that IAM denials use this name; check the message for is not authorized to perform) → guides/iam/fix-access-denied.mdMessage contains is not authorized to perform → IAM/KMS denial; otherwise signing. aws sts get-caller-identity with the same credentials
UnrecognizedClientExceptionNo (fix keys)Access key ID or session token invalid. Usually expired or wrong-account credentials (reference/sts/errors.md)aws sts get-caller-identity with the same credentials; check the session token's expiry
MissingAuthenticationTokenException / IncompleteSignatureExceptionNoMissing or malformed authorization header. Usually a hand-built request, not SDK useOnly if not using an SDK: inspect the request's Authorization header
ReplicatedWriteConflictExceptionYesMulti-Region strongly consistent global tables: another Region is writing the same itemdescribe-table → MultiRegionConsistency is STRONG; look for concurrent writers to that key in other Regions (the field name is from the API model)
TransactionCanceledExceptionDependsA transaction failed. Its cancellation reasons say which item and why, for example a condition. The exception carries CancellationReasons, one entry per item in request order (member name from the API model; the per-item order is the hub's reading)Read CancellationReasons: each entry has a Code (for example ConditionalCheckFailed) for the item at that position
InternalServerError (500) / ServiceUnavailable (503)YesServer side. A write may have succeeded: retry TransactWriteItems freely, but for PutItem/UpdateItem/DeleteItem read the item first or make the write conditionalRead the item back before retrying a non-idempotent write

Not errors, but often treated as one

  • UnprocessedItems / UnprocessedKeys in batch responses are partial successes. Resubmit those with backoff.
  • LastEvaluatedKey in a Query or Scan response means there are more pages (1 MB per call). It isn't truncation.
  • Empty Item from GetItem means the item doesn't exist. No error is raised.

Finding the hot key

Sustained throttling on part of a table usually means writes or reads concentrate on a few partition key values. CloudWatch Contributor Insights for DynamoDB shows the most-accessed keys. Turn it on with aws dynamodb update-contributor-insights --table-name <t> --contributor-insights-action ENABLE (operation from the API model). The fix is a key design that spreads load (guides/dynamodb/design-and-access.md).

When none of these fits

Keep the request ID from the SDK error and the table's CloudWatch metrics for the minute it happened: ThrottledRequests, consumed versus provisioned capacity, and per-index metrics. Search the hub for the exact message. For conditional-write surprises, read the item and compare it with the ConditionExpression. If a global table is involved, check which Region wrote last (reference/dynamodb/ttl-pitr-and-global-tables.md).

Read this document as markdown — the same bytes an agent receives.