DynamoDB IdempotentParameterMismatchException

TL;DR — Tu as appelé TransactWriteItems avec un ClientRequestToken déjà utilisé au cours des 10 dernières minutes, mais le reste de la requête a changé. Le token promet « c'est la même transaction, réessayée » — donc DynamoDB rejette une réutilisation de token dont la charge utile diffère. Ne réutilise le token que pour des tentatives strictement identiques ; génère un nouveau token (un UUID) pour chaque nouvelle transaction logique.

Ce que ça signifie

IdempotentParameterMismatchException: DynamoDB rejected the request because
you retried a request with a different payload but with an idempotent token
that was already used.

ClientRequestToken rend TransactWriteItems idempotent : plusieurs appels identiques avec le même token ont l'effet d'un seul appel, ce qui te protège d'appliquer deux fois une transaction quand un délai d'attente masque le fait que la première tentative a abouti ou non. Un token reste valide pendant 10 minutes après la fin de la première requête qui l'a utilisé. Si une requête arrive dans cette fenêtre avec le même token mais des paramètres différents, DynamoDB ne peut pas la traiter comme une nouvelle tentative — et refuse aussi de la traiter comme une nouvelle transaction. HTTP 400, non réessayable en l'état.

Pourquoi ça arrive

• Un token statique ou codé en dur — la même chaîne de token est envoyée pour chaque transaction, donc la seconde transaction (différente) entre en collision avec la première.
• Token dérivé de quelque chose de trop grossier — par ex. l'ID utilisateur ou le nom de table, donc deux transactions différentes pour le même utilisateur partagent un token.
• La nouvelle tentative a reconstruit la requête différemment — un horodatage, une valeur de TTL ou un ID généré à l'intérieur d'un élément a changé entre la première tentative et la nouvelle, de sorte que la « même » transaction ne correspond plus octet pour octet.
• Deux chemins de code partagent une source de token — des workers parallèles amorcés avec la même valeur.

Comment corriger

1. Génère un token unique par transaction logique — un UUID au point où la transaction est composée :

   import {randomUUID} from 'node:crypto';
   
   await client.send(new TransactWriteItemsCommand({
     ClientRequestToken: token, // created ONCE per logical transaction
     TransactItems: [...]
   }));

2. Garde le token avec la requête lors de la nouvelle tentative — réessaie le même objet de requête déjà construit, pas un objet reconstruit, pour que rien dans la charge utile ne puisse dériver. (Les SDK AWS le font correctement pour leurs nouvelles tentatives automatiques ; le bug vient presque toujours d'une nouvelle tentative au niveau applicatif qui recompose la requête.)

3. Fige les valeurs volatiles avant de composer — horodatages et ID générés doivent être calculés une fois et réutilisés lors de la nouvelle tentative, pas réévalués.

4. Ne réutilise pas un token après 10 minutes en espérant l'idempotence — au-delà de la fenêtre, la requête est traitée comme entièrement nouvelle et sera appliquée à nouveau.

L'application de bureau DynoTable te permet d'inspecter les éléments exacts qu'une transaction a touchés, ce qui fait de « ma première tentative a-t-elle vraiment abouti ? » une recherche plutôt qu'une supposition.

Erreurs liées

• TransactionCanceledException — la transaction s'est exécutée et a été annulée.
• TransactionConflictException — une transaction concurrente a touché le même élément.
• TransactWriteItems: too many items
• Exemple de code : TransactWriteItems en Node.js — montre l'utilisation de ClientRequestToken.
• Apprends : Transactions DynamoDB

References

• TransactWriteItems — Amazon DynamoDB API Reference (ClientRequestToken, IdempotentParameterMismatchException)
• Amazon DynamoDB Transactions: How it works — Developer Guide (idempotency)
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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