DynamoDB IdempotentParameterMismatchException

In breve — Hai chiamato TransactWriteItems con un ClientRequestToken che era già stato usato negli ultimi 10 minuti, ma il resto della richiesta è cambiato. Il token promette "questa è la stessa transazione, riprovata" — quindi DynamoDB rifiuta un riutilizzo del token il cui payload differisce. Riutilizza il token solo per retry byte-identici; genera un token nuovo (un UUID) per ogni nuova transazione logica.

Cosa significa

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

ClientRequestToken rende TransactWriteItems idempotente: più chiamate identiche con lo stesso token hanno l'effetto di una singola chiamata, il che ti protegge dal doppio applicazione di una transazione quando un timeout nasconde se il primo tentativo è andato a buon fine. Un token resta valido per 10 minuti dopo che la prima richiesta che lo ha usato è completata. Se una richiesta arriva dentro quella finestra con lo stesso token ma parametri diversi, DynamoDB non può trattarla come un retry — e si rifiuta di trattarla anche come una nuova transazione. HTTP 400, non ripetibile così com'è.

Perché accade

• Un token statico o hardcoded — la stessa stringa di token viene inviata per ogni transazione, quindi la seconda (diversa) transazione collide con la prima.
• Token derivato da qualcosa troppo grossolano — es. l'ID utente o il nome della tabella, così due transazioni diverse per lo stesso utente condividono un token.
• Il retry ha ricostruito la richiesta in modo diverso — un timestamp, un valore TTL, o un ID generato all'interno di un Item è cambiato tra il primo tentativo e il retry, così la "stessa" transazione non corrisponde più byte per byte.
• Due percorsi di codice condividono una fonte di token — worker paralleli inizializzati con lo stesso valore.

Come correggerlo

1. Genera un token unico per transazione logica — un UUID nel punto in cui la transazione viene composta:

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

2. Mantieni il token con la richiesta quando riprovi — riprova lo stesso oggetto richiesta già costruito, non uno ricostruito, così nulla nel payload possa derivare. (Gli AWS SDK fanno questo correttamente per i loro retry automatici; il bug è quasi sempre un retry a livello di applicazione che ricompone la richiesta.)

3. Fissa i valori volatili prima di comporre — timestamp e ID generati devono essere calcolati una volta e riutilizzati nel retry, non rivalutati.

4. Non riutilizzare un token dopo 10 minuti aspettandoti l'idempotenza — oltre la finestra la richiesta è trattata come nuova di zecca e verrà applicata di nuovo.

L'app desktop DynoTable ti permette di ispezionare gli Item esatti che una transazione ha toccato, il che rende "il mio primo tentativo è andato a buon fine?" una ricerca invece di una supposizione.

Errori correlati

• TransactionCanceledException — la transazione è stata eseguita e ha subito il rollback.
• TransactionConflictException — una transazione concorrente ha toccato lo stesso Item.
• TransactWriteItems: too many items
• Esempio di codice: TransactWriteItems in Node.js — mostra l'uso di ClientRequestToken.
• Impara: DynamoDB transactions

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

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