Error: DynamoDB throttling error

DynamoDB throttling means a table, index, or partition cannot accept the requested throughput, or a configured limit was reached. It affects both provisioned and on-demand tables. Inspect ThrottlingReasons and the resource ARN before deciding which setting to change.

Use the reason, not just the exception name

• ProvisionedThroughputExceeded: increase the affected table or GSI’s provisioned capacity, review auto-scaling targets, and account for scaling delay.
• KeyRangeThroughputExceeded: investigate concentrated access to a partition. More aggregate capacity alone may not fix a hot key; spread keys, reduce concurrency, cache suitable reads, or redesign the access pattern.
• AccountLimitExceeded: check the applied table or index throughput quota in that Region and request a quota increase if appropriate.
• MaxOnDemandThroughputExceeded: review the maximum throughput cap configured on the affected on-demand table or GSI. Raising a cap can raise spending.

A reason such as IndexWriteKeyRangeThroughputExceeded identifies an index write bottleneck. A throttled GSI can also cause base-table writes to fail. Check index dimensions in CloudWatch rather than looking only at aggregate table consumption.

Capture useful evidence

try {
  await db.send(command); // Existing SDK v3 client and operation.
} catch (error) {
  console.error({
    name: error.name,
    requestId: error.$metadata?.requestId,
    reasons: error.ThrottlingReasons
  });
  throw error;
}

Use a current SDK so the modeled reason fields are available. Correlate the exception with the appropriate read or write throttle metric and Contributor Insights. Do not log item contents or credentials as diagnostic context.

Retry without amplifying overload

Keep SDK retries bounded and use exponential backoff with jitter. Limit concurrent work and smooth bursts. For successful batch responses, separately retry UnprocessedItems or UnprocessedKeys. Persistent retries are a signal to fix capacity or access patterns, not an unlimited queue.

Before a planned spike, check warm throughput and pre-warm where appropriate. On-demand mode still has ramp-up behavior, quotas, partition limits, and optional caps. Switching modes is not a universal throttling fix.

See the throttling guide and AWS documentation.