Fix: ProvisionedThroughputExceededException (DynamoDB)

You are seeing ProvisionedThroughputExceededException because DynamoDB rejected a read or write: the request rate went past the throughput available to that table, index, or a single partition. This guide walks through stabilizing the workload, finding the real cause (which is often a hot partition rather than low table capacity), and fixing it so it does not come back.

What this error means

DynamoDB serves each table from one or more physical partitions. Provisioned capacity, measured in read capacity units and write capacity units, is divided across those partitions. A request is throttled when it exceeds either the total provisioned capacity or the share allocated to the specific partition it targets. A small burst allowance absorbs short spikes, but once that is drained, DynamoDB returns this exception.

The important nuance: capacity is distributed by partition key. If most traffic hits one key, that partition can throttle even while the table’s total consumed capacity sits well below what you provisioned. Global secondary indexes have their own capacity and can throttle independently of the base table.

Common causes

• A hot partition: one partition key value (or a narrow range) receives a disproportionate share of reads or writes, so a single partition is saturated while the table looks underused.
• A hot GSI: a global secondary index has its own provisioned capacity and its own key distribution, and it can throttle on its own.
• A genuine traffic spike on provisioned mode where capacity was set too low or auto scaling reacted too slowly.
• Retries or exponential backoff disabled, or a tight loop that fires requests faster than backoff can pace them, so the SDK surfaces the exception instead of absorbing it.
• Large scans or batch operations concentrated in a short window, draining burst capacity.

How to fix it

1. Stabilize

First, make sure the SDK is actually retrying. The AWS SDKs retry this exception with exponential backoff by default, so confirm retries are not disabled and consider raising the retry count for the client. In Python with boto3:

import boto3
from botocore.config import Config

config = Config(retries={"max_attempts": 10, "mode": "adaptive"})
dynamodb = boto3.client("dynamodb", config=config)

For immediate relief during an incident, either raise provisioned capacity or switch the table to on-demand mode, which scales automatically:

aws dynamodb update-table \
  --table-name Orders \
  --billing-mode PAY_PER_REQUEST

If you prefer to stay on provisioned mode, raise the numbers temporarily:

aws dynamodb update-table \
  --table-name Orders \
  --billing-mode PROVISIONED \
  --provisioned-throughput ReadCapacityUnits=200,WriteCapacityUnits=200

2. Diagnose

Compare consumed against provisioned in CloudWatch, and look for throttling. Pull the throttled request count for the last hour:

aws cloudwatch get-metric-statistics \
  --namespace AWS/DynamoDB \
  --metric-name ThrottledRequests \
  --dimensions Name=TableName,Value=Orders \
  --start-time 2026-07-13T00:00:00Z \
  --end-time 2026-07-13T01:00:00Z \
  --period 60 \
  --statistics Sum

Also review ConsumedReadCapacityUnits and ConsumedWriteCapacityUnits against the provisioned values. If consumed is low but you are still throttled, you have a hot partition. Enable Contributor Insights to find the offending key:

aws dynamodb update-contributor-insights \
  --table-name Orders \
  --contributor-insights-action ENABLE

Then read the most accessed keys from the MostAccessedKeys rules in CloudWatch Contributor Insights.

3. Fix

• Redesign the partition key for high cardinality so traffic spreads evenly. For write heavy hot keys, apply write sharding by appending a suffix (for example, userId#0 through userId#9) and fan reads across the shards.
• If a GSI is the hot spot, redesign its partition key or raise its own capacity.
• Move to on-demand mode, or enable auto scaling on provisioned capacity so it tracks demand.
• Cache hot reads with DynamoDB Accelerator (DAX) to take pressure off the base table.
• Batch and spread writes over time rather than firing them in a tight burst.

How to prevent it

• Choose high-cardinality partition keys from the start, and model access patterns before you pick keys.
• Add write sharding for any key you expect to be hot, such as a global counter or a single tenant.
• Set CloudWatch alarms on ThrottledRequests and keep Contributor Insights enabled so a hot key shows up early.
• Prefer on-demand mode or auto scaling for workloads with unpredictable traffic.
• Load test near expected peak so throttling appears in staging, not production.

When to call a senior engineer

If throttling persists after moving to on-demand mode, the problem is almost certainly a single hot partition key that needs a data model change, and that is harder to fix safely under load. Reworking a partition key or a GSI usually means a backfill and a careful cutover across live traffic. If you are mid-incident, unsure whether the hot key can be sharded without breaking existing queries, or facing a migration you cannot roll back, bring in someone who has done DynamoDB key redesigns before.