DynamoDB ProvisionedThroughputExceededException

In breve — Stai leggendo/scrivendo più velocemente di quanto la tabella o l'indice possa servire. Passa la tabella alla capacità on-demand, aumenta le RCU/WCU con provisioning (o abilita l'auto-scaling), mantieni i retry con backoff esponenziale predefiniti dell'SDK, e distribuisci il traffico così una partition key non sia hot.

Cosa significa

ProvisionedThroughputExceededException: You exceeded your maximum allowed
provisioned throughput for a table or for one or more global secondary indexes.

Su una tabella a capacità con provisioning, hai superato le unità di capacità di lettura/scrittura — o complessivamente, o (più spesso) su una singola partizione. È un HTTP 400 ma, a differenza di una ValidationException, è ripetibile: gli AWS SDK lo riprovano automaticamente con backoff esponenziale, quindi occasionali sono normali. Quelli persistenti significano un vero sotto-provisioning o una chiave hot. L'errore porta campi ThrottlingReason (es. TableReadProvisionedThroughputExceeded) più l'ARN della risorsa interessata, così puoi capire quale tabella o indice ha fatto throttling e su quale tipo di operazione.

Perché succede

Capacità sotto-dimensionata per il traffico effettivo.
Una partizione hot — traffico concentrato su una partition key, quindi la quota di capacità di una singola partizione è esaurita mentre la tabella sembra sottoutilizzata complessivamente.
Traffico a raffica più veloce di quanto l'auto-scaling possa reagire — regola la capacità in risposta alle metriche di capacità consumata, quindi un improvviso cambiamento a gradino fa throttling prima che lo scale-up atterri.
Uno scan grande o un import di massa che consuma tutta la capacità in una volta.
Un GSI la cui capacità è inferiore al tasso di scrittura — un GSI sottoposto a throttling fa throttling sulla tabella base.

Come risolverlo

Passa alla capacità on-demand se il traffico è imprevedibile — scala automaticamente e questo errore di fatto scompare (paghi per richiesta invece).
Aumenta le RCU/WCU con provisioning oppure abilita l'auto-scaling con un utilizzo target ragionevole se resti su provisioning.
Mantieni i retry con backoff esponenziale — l'SDK lo fa per impostazione predefinita; non disabilitarlo. Usa la modalità adaptive retry per carichi a raffica.
Correggi la partizione hot — aumenta la cardinalità della chiave / fai write-sharding della chiave hot così il carico si distribuisca tra le partizioni.
Modera i job di massa e metti in cache le letture hot (DAX o una cache applicativa) per scaricare la pressione di lettura.

FAQ

Come correggo ProvisionedThroughputExceededException? Stai leggendo o scrivendo più velocemente di quanto la tabella o l'indice possa servire. Passa la tabella alla capacità on-demand, aumenta le RCU/WCU con provisioning (o abilita l'auto-scaling), mantieni i retry con backoff esponenziale predefiniti dell'SDK, e distribuisci il traffico così una singola partition key non sia hot.

Riproducilo

Fai il provisioning di una tabella a 1 RCU, inserisci un Item poco sotto i 4 KB, poi rileggilo in modo fortemente coerente in un loop stretto:

import boto3
ddb = boto3.client('dynamodb', region_name='us-east-1')
# table created with ProvisionedThroughput={'ReadCapacityUnits': 1, 'WriteCapacityUnits': 1}
ddb.put_item(TableName='my-table', Item={'pk': {'S': 'A'}, 'blob': {'S': 'x' * 3500}})
while True:
    ddb.get_item(TableName='my-table', Key={'pk': {'S': 'A'}}, ConsistentRead=True)

Output reale:

ProvisionedThroughputExceededException: The level of configured provisioned throughput for the table was exceeded. Consider increasing your provisioning level with the UpdateTable API.
HTTP 400

Sono servite 49 letture per innescarlo, su una tabella appena creata con i retry dell'SDK disabilitati. Quel numero è la parte interessante: una tabella a 1 RCU non fallisce alla seconda richiesta, perché DynamoDB ti presta prima la capacità burst accumulata — quindi un load test che si ferma troppo presto segnalerà come sana una tabella che non lo è. L'altra metà dell'illusione è l'SDK, che per impostazione predefinita riprova per te le richieste sottoposte a throttling; disabilita i retry come sopra, oppure questo errore resta invisibile finché non diventa invece un problema di latenza.

Errori correlati

ThrottlingException — limiti di rate account/control-plane.
Throttled despite spare capacity (hot partition) — una partition key che assorbe il traffico.
On-demand throughput exceeded — l'equivalente in modalità on-demand.
ItemCollectionSizeLimitExceededException
Esempio di codice: BatchWriteItem in Node.js — il pattern retry-with-backoff di UnprocessedItems.
Impara: On-demand vs provisioned · Hot partitions

Riferimenti

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.

Riprodotto il 2026-07-26 sul servizio DynamoDB live in us-east-1 tramite boto3 1.43.56, su una tabella con provisioning a 1 RCU e i retry dell'SDK disabilitati — l'output qui sopra è riportato alla lettera.