Fix DynamoDB ProvisionedThroughputExceededException

ProvisionedThroughputExceededException means DynamoDB throttled your request — you asked for more read or write throughput than was available at that moment:

ProvisionedThroughputExceededException: The level of configured provisioned throughput for the table was exceeded

The AWS SDKs retry throttled requests automatically with exponential backoff, so if this exception actually reaches your code, the retries were exhausted. That’s a signal to fix the cause, not to pile on more retries. There are three main causes.

Cause 1: Hot partition (the subtle one)

DynamoDB distributes items across partitions by partition key. Each partition has its own throughput ceiling. If most of your traffic targets a single key — a GLOBAL counter, today’s date, a celebrity user — that one partition throttles while the table as a whole looks under-utilized.

This is why you can be throttled at, say, 500 WCU on a table provisioned for 3,000: the table has headroom, but one partition doesn’t.

Fixes:

• Spread the key. Add a suffix or shard to high-traffic keys (COUNTER#3 of N shards) and aggregate across shards.
• Rethink the access pattern. A monotonically increasing key (timestamps, sequential ids) concentrates writes on one partition. Introduce entropy in the partition key. See Best practices.

Cause 2: Under-provisioned capacity (provisioned mode)

On provisioned tables, sustained traffic above your RCU/WCU gets throttled once burst credits are spent.

• Enable auto scaling so capacity tracks demand, or
• Switch to on-demand mode if traffic is spiky or unpredictable — you pay per request and DynamoDB handles scaling.

Check your consumed vs. provisioned capacity in CloudWatch (ConsumedReadCapacityUnits / ConsumedWriteCapacityUnits against the provisioned values) and watch the ThrottledRequests metric. See Capacity and pricing for how the modes differ.

Cause 3: Expensive reads — big Scans and large items

A full-table Scan reads every item and consumes capacity for all of it, easily spiking throughput and throttling everything else on the table. Mitigations:

• Prefer Query with a key condition over Scan wherever possible.
• If you must scan, page with a smaller Limit and, for background jobs, cap throughput deliberately rather than reading as fast as possible.
• Watch item size: RCUs/WCUs are charged per 4 KB (reads) / 1 KB (writes) rounded up. Large items multiply capacity per operation. Keep hot items lean; offload big blobs to S3.

Cause 4: Index throttling

A Global Secondary Index has its own provisioned throughput. If a GSI is under-provisioned, writes to the base table can be throttled because they can’t propagate to the index. Provision (or auto-scale) GSIs alongside the base table, and remember every write fans out to each GSI whose keys it affects.

Diagnostic checklist

1. Which metric? Check CloudWatch ThrottledRequests, ConsumedRead/WriteCapacityUnits, and per-index consumption.
2. Hot key? Is traffic concentrated on one partition key? (Table has headroom but you’re still throttled → almost certainly hot partition.)
3. Mode & scaling — provisioned without auto scaling? Consider auto scaling or on-demand.
4. Scans — replace Scan with Query, or throttle background scans with a small Limit.
5. Item size — are large items inflating capacity per op?
6. GSIs — is an index under-provisioned relative to the base table?

Find the hot spots visually

Throttling is hard to reason about from logs alone — you need to see which tables and access patterns burn capacity. Tablyne surfaces your tables, indexes and item sizes in one place, so oversized items and query-vs-scan choices are easy to spot before they turn into throttling. Download Tablyne free to inspect your tables and query them efficiently.