DynamoDB ProvisionedThroughputExceededException

TL;DR — Tu lis/écris plus vite que la table ou l'index ne peut servir. Bascule la table en capacité on-demand, augmente les RCU/WCU provisionnés (ou active l'auto-scaling), garde les reprises exponentielles avec backoff par défaut du SDK, et répartis le trafic pour qu'une seule clé de partition ne soit pas chaude.

Ce que ça signifie

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

Sur une table à capacité provisionnée, tu as dépassé les unités de capacité de lecture/écriture — soit globalement, soit (plus souvent) sur une seule partition. C'est un HTTP 400 mais, contrairement à une ValidationException, il est réessayable : les SDK AWS le réessaient automatiquement avec un backoff exponentiel, donc quelques-uns de temps en temps sont normaux. Des occurrences persistantes traduisent un réel sous-provisionnement ou une clé chaude. L'erreur porte les champs ThrottlingReason (par ex. TableReadProvisionedThroughputExceeded) plus l'ARN de la ressource affectée, ce qui te permet de savoir quelle table ou quel index a été limité et sur quel type d'opération.

Pourquoi ça arrive

Capacité sous-provisionnée pour le trafic réel.
Une partition chaude — le trafic concentré sur une seule clé de partition, si bien que la part de capacité d'une seule partition est épuisée alors que la table paraît sous-utilisée globalement.
Un trafic en pics plus rapide que ce que l'auto-scaling peut suivre — il ajuste la capacité en réponse aux métriques de capacité consommée, donc un changement brusque provoque un throttle avant que la montée en charge n'arrive.
Un gros scan ou un import en masse consommant toute la capacité d'un coup.
Un GSI dont la capacité est inférieure au débit d'écriture — un GSI limité limite la table de base.

Comment le corriger

Bascule en capacité on-demand si le trafic est imprévisible — elle monte en charge automatiquement et cette erreur disparaît effectivement (tu paies à la requête à la place).
Augmente les RCU/WCU provisionnés ou active l'auto-scaling avec un taux d'utilisation cible raisonnable si tu restes en provisionné.
Garde les reprises exponentielles avec backoff — le SDK le fait par défaut ; ne le désactive pas. Utilise le mode de reprise adaptatif pour les charges de travail en pics.
Corrige la partition chaude — augmente la cardinalité de la clé / répartis la clé chaude en shards d'écriture pour que la charge se répartisse entre les partitions.
Régule les jobs en masse et mets en cache les lectures chaudes (DAX ou un cache applicatif) pour délester la pression en lecture.

FAQ

Comment corriger ProvisionedThroughputExceededException ? Tu lis ou écris plus vite que la table ou l'index ne peut servir. Bascule la table en capacité on-demand, augmente les RCU/WCU provisionnés (ou active l'auto-scaling), garde les reprises exponentielles avec backoff par défaut du SDK, et répartis le trafic pour qu'une seule clé de partition ne soit pas chaude.

Reproduire l'erreur

Provisionne une table à 1 RCU, écris-y un élément d'un peu moins de 4 Ko, puis relis-le en lecture fortement cohérente dans une boucle serrée :

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)

Sortie réelle :

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

Il a fallu 49 lectures pour la déclencher, sur une table fraîchement créée et avec les reprises du SDK désactivées. C'est ce nombre qui est intéressant : une table à 1 RCU n'échoue pas à la deuxième requête, parce que DynamoDB te prête d'abord la capacité de burst accumulée — un test de charge qui s'arrête trop tôt déclarera donc saine une table qui ne l'est pas. L'autre moitié de l'illusion vient du SDK, qui réessaie par défaut les requêtes throttlées à ta place ; désactive les reprises comme ci-dessus, sinon cette erreur reste invisible jusqu'à devenir un problème de latence.

Erreurs liées

ThrottlingException — limites de débit compte/plan de contrôle.
Throttled despite spare capacity (hot partition) — une clé de partition qui absorbe tout le trafic.
On-demand throughput exceeded — l'équivalent en mode on-demand.
ItemCollectionSizeLimitExceededException
Exemple de code : BatchWriteItem en Node.js — le motif de reprise avec backoff des UnprocessedItems.
En savoir plus : On-demand vs provisioned · Hot partitions

Références

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.

Reproduit le 2026-07-26 sur le service DynamoDB réel dans us-east-1 via boto3 1.43.56, sur une table provisionnée à 1 RCU et avec les reprises du SDK désactivées — la sortie ci-dessus est reproduite telle quelle.