Le throttling DynamoDB — pourquoi il arrive et comment le corriger

Le throttling, c'est DynamoDB qui te dit qu'une limite a été atteinte — sauf qu'il y a quatre limites différentes, trois exceptions différentes, et que le correctif d'une cause aggrave une autre. Augmenter la capacité de la table ne fait rien contre une clé surchargée ; passer en on-demand ne fait rien non plus contre une clé surchargée, et peut throttler selon ses propres règles. Ce guide est le chapeau : quelle limite tu as réellement atteinte, comment les métriques les distinguent, et le correctif qui correspond à chaque cause.

Pourquoi DynamoDB throttle-t-il mes requêtes ?

L'une des quatre raisons documentées : une seule partition a dépassé sa limite fixe par partition de 3 000 unités de lecture ou 1 000 unités d'écriture par seconde (une clé surchargée — ça arrive dans les deux modes de capacité) ; la table a dépassé ses RCU/WCU provisionnés (mode provisionné) ; le compte a dépassé son quota de débit au niveau de la région ; ou une table on-demand a grossi plus vite que le double de son précédent pic en moins de 30 minutes. Le correctif dépend de laquelle il s'agissait, alors diagnostique avant de redimensionner quoi que ce soit.

Les quatre scénarios de throttling

La page de dépannage d'AWS elle-même découpe le throttling en exactement quatre cas :

1. Débit de plage de clés (partition) dépassé — les deux modes. Chaque partition est conçue pour un maximum de 3 000 unités de lecture et 1 000 unités d'écriture par seconde (doc sur les clés de partition), et la taille des items compte dedans. Aucun réglage au niveau de la table ne relève ce plafond ; seule la conception des clés le répartit. C'est le cas de la partition surchargée, et la table peut sembler massivement sous-utilisée pendant qu'elle throttle.
2. Débit provisionné dépassé — mode provisionné. La consommation a dépassé les RCU/WCU provisionnés de la table (ou d'un GSI), et le coussin d'environ 5 minutes de capacité de rafale a été épuisé. L'échelle des correctifs est du côté capacité : l'auto-scaling, un provisionnement plus élevé, ou un changement de mode.
3. Quota au niveau du compte dépassé. Les quotas de compte régionaux plafonnent le débit total — par défaut 40 000 unités de lecture et 40 000 unités d'écriture par table, et pour le mode provisionné 80 000 RCU et 80 000 WCU par compte (quotas) ; ce sont des valeurs par défaut initiales, ajustables via Service Quotas, et les tables on-demand n'ont pas de quota de débit au niveau du compte.
4. Débit maximal on-demand dépassé. L'on-demand absorbe instantanément jusqu'au double du précédent pic ; dépasse le double en moins de 30 minutes et il peut throttler (doc on-demand). Les nouvelles tables on-demand tiennent 4 000 écritures/s et 12 000 lectures/s d'emblée. Pour un pic en marche d'escalier planifié (lancement, promotion, migration), préchauffe la table avec le warm throughput au lieu d'espérer que la montée soit progressive.

Les trois exceptions, et le champ qui nomme la cause

• ProvisionedThroughputExceededException — throttling de capacité en mode provisionné : « vous avez dépassé le débit provisionné maximal autorisé pour une table ou pour un ou plusieurs index secondaires globaux ». Les détails sont sur la page d'erreur dédiée.
• ThrottlingException — des opérations du plan de contrôle émises trop vite et, sur les tables on-demand, toute opération du plan de données dont le rythme est trop élevé (c'est l'exception derrière la règle du double pic — voir la page d'erreur on-demand et ThrottlingException).
• RequestLimitExceeded — les limites de débit au niveau du compte : le territoire du « contacte le support AWS », couvert sur sa page d'erreur.

Les trois sont marquées comme réessayables, et les trois portent désormais des valeurs ThrottlingReason structurées de la forme ressource + opération + limite — TableReadProvisionedThroughputExceeded, IndexWriteKeyRangeThroughputExceeded, TableWriteAccountLimitExceeded, et ainsi de suite (référence des erreurs). Lis la raison, pas seulement la classe d'exception : elle nomme la ressource (table ou index), le sens de l'opération, et laquelle des quatre limites tu as atteinte — c'est exactement le diagnostic. Une réserve que la documentation impose elle-même : les pages d'AWS divergent sur le fait que le throttling de limite de compte remonte en RequestLimitExceeded ou en ThrottlingException avec une raison AccountLimitExceeded — indexe donc ton traitement sur la chaîne de la raison.

Ce qui absorbe la charge avant que tu sois throttlé

Deux mécanismes intégrés adoucissent les limites, et connaître leurs bords explique le « ça marchait hier » :

• La capacité de rafale conserve jusqu'à cinq minutes (300 secondes) de capacité de lecture et d'écriture inutilisée pour les pics — mais DynamoDB peut aussi la consommer pour de la maintenance en arrière-plan « sans préavis », et AWS note explicitement que les détails peuvent changer. Ne conçois pas en comptant sur la rafale ; traite-la comme de la chance.
• La capacité adaptative déplace automatiquement et instantanément le débit vers les partitions surchargées et peut isoler un item fréquemment accédé sur sa propre partition — mais seulement « à condition que le trafic ne dépasse pas la capacité provisionnée totale de votre table ni la capacité maximale de la partition ». Elle rééquilibre le déséquilibre ; elle ne relève jamais le plafond par partition de 3 000/1 000, et elle ne divise pas les collections d'items quand la table a un LSI. Les pages de dépannage actuelles d'AWS s'appuient sur le split-for-heat — la division des partitions sous une chaleur soutenue — qui prend du temps et n'aide en rien face à une seule clé surchargée.

Diagnostique-le depuis les métriques

CloudWatch distingue les requêtes des événements, et cette distinction fait le diagnostic (référence des métriques) :

• ThrottledRequests compte une requête une fois si un événement en son sein a été throttlé — un PutItem sur une table avec trois GSI, c'est une requête mais quatre événements d'écriture. Dans un batch, elle ne s'incrémente que si tous les items ont été throttlés.
• ReadThrottleEvents / WriteThrottleEvents comptent chaque événement throttlé — un BatchGetItem de 10 items, c'est 10 événements GetItem. Pour voir les throttles en écriture d'un GSI, tu dois interroger la métrique avec à la fois TableName et GlobalSecondaryIndexName — c'est comme ça que la contre-pression GSI se cache des tableaux de bord au niveau de la table.
• Les plus récentes métriques d'événements spécifiques à la raison (WriteProvisionedThroughputThrottleEvents, ReadKeyRangeThroughputThrottleEvents, …AccountLimitThrottleEvents, …MaxOnDemandThroughputThrottleEvents) répartissent les décomptes selon ces mêmes quatre causes — si ta région les expose, elles répondent directement à la question « quelle limite ».

Un piège : les SDK réessaient automatiquement les requêtes throttlées — le mode de nouvelles tentatives standard fait 3 tentatives au total par défaut (le déploiement opt-in des nouvelles tentatives de 2026 fait passer les clients DynamoDB à 4 tentatives avec des délais plus serrés). Un throttling léger se manifeste donc en latence, pas en erreurs ; surveille les métriques de throttling, pas seulement tes journaux d'exceptions.

Contre-pression GSI : le throttle qui désigne la mauvaise table

Si un GSI n'arrive pas à absorber l'amplification d'écriture, « DynamoDB throttle les écritures vers la table de base pour maintenir la cohérence des données » (doc sur le throttling des GSI) — même quand la table de base a de la capacité en réserve. Le ResourceArn de l'exception désigne l'index, mais l'opération qui a échoué est ton écriture sur la table de base. Chaque index a besoin de son propre plan de capacité (et de sa propre politique d'auto-scaling) ; pourquoi un GSI throttle les écritures de la table de base détaille la mécanique.

Fais correspondre le correctif à la cause

Fais-le dans DynoTable

La plupart des throttlings qu'on s'inflige soi-même commencent par des lectures qui coûtent plus cher qu'elles n'en ont l'air : un Scan filtré consomme la lecture entière dans tous les cas. L'aperçu du coût avant exécution de DynoTable montre si une instruction devient un Query ou un Scan, l'index qu'elle frappe, et une estimation du coût en lecture avant que tu le dépenses — le correctif de throttling le moins cher, c'est la lecture coûteuse que tu n'as pas lancée. Le guide Scan vs Query couvre la différence ; le calculateur de taille d'item gratuit transforme un vrai item en ces chiffres RCU/WCU dans lesquels les limites ci-dessus se mesurent.

Pièges et prochaines étapes

• Les nouvelles tentatives amplifient la surcharge. Le backoff est intégré aux SDK, mais une boucle de nouvelles tentatives serrée au niveau applicatif, par-dessus celles du SDK, multiplie la pression sur exactement la partition qui peine.
• Les batches masquent le throttling partiel. Un BatchWriteItem renvoie les items non traités au lieu de lever une exception tant qu'un item réussit — vérifie UnprocessedItems, pas seulement les exceptions.
• La vue au niveau de la table ment sur les GSI. Trace toujours les événements de throttling par index ; les tableaux de bord de la table de base paraissent propres pendant une contre-pression.
• Les correctifs de capacité prennent des minutes ; la conception des clés est pour toujours. L'auto-scaling réagit en ~5 minutes, les augmentations de quota passent par un ticket de support, mais une clé surchargée te suit dans tous les modes de capacité — investis l'effort là où il compose : comment fonctionnent les clés de partition.

Télécharge DynoTable pour voir le plan Scan-vs-Query et le coût en lecture de chaque requête avant qu'elle s'exécute contre ta capacité.