DynamoDB IdempotentParameterMismatchException

TL;DR — Llamaste a TransactWriteItems con un ClientRequestToken que ya se usó en los últimos 10 minutos, pero el resto de la solicitud cambió. El token promete "esta es la misma transacción, reintentada" — así que DynamoDB rechaza la reutilización de un token cuyo payload difiere. Reutiliza el token solo para reintentos idénticos byte a byte; genera un token nuevo (un UUID) para cada nueva transacción lógica.

Qué 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 hace que TransactWriteItems sea idempotente: múltiples llamadas idénticas con el mismo token tienen el efecto de una sola llamada, lo que te protege de aplicar dos veces una transacción cuando un timeout oculta si el primer intento aterrizó. Un token sigue siendo válido durante 10 minutos después de que se complete la primera solicitud que lo usó. Si llega una solicitud dentro de esa ventana con el mismo token pero parámetros distintos, DynamoDB no puede tratarla como un reintento — y se niega a tratarla como una nueva transacción también. HTTP 400, no reintentable tal cual.

Por qué ocurre

• Un token estático o hardcodeado — se envía la misma cadena de token para cada transacción, así que la segunda transacción (distinta) colisiona con la primera.
• Token derivado de algo demasiado grueso — p. ej. el ID de usuario o el nombre de la tabla, así que dos transacciones distintas para el mismo usuario comparten un token.
• El reintento reconstruyó la solicitud de forma distinta — una marca de tiempo, un valor de TTL o un ID generado dentro de un Item cambió entre el primer intento y el reintento, así que la "misma" transacción ya no coincide byte a byte.
• Dos rutas de código comparten un origen de token — workers paralelos sembrados con el mismo valor.

Cómo solucionarlo

1. Genera un token único por transacción lógica — un UUID en el punto donde se compone la transacción:

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

2. Mantén el token con la solicitud al reintentar — reintenta el mismo objeto de solicitud ya construido, no uno reconstruido, para que nada del payload pueda derivar. (Los AWS SDK hacen esto correctamente para sus reintentos automáticos; el bug es casi siempre un reintento a nivel de aplicación que recompone la solicitud.)

3. Fija los valores volátiles antes de componer — las marcas de tiempo y los IDs generados deben calcularse una vez y reutilizarse en el reintento, no reevaluarse.

4. No reutilices un token después de 10 minutos esperando idempotencia — pasada la ventana, la solicitud se trata como nueva y se aplicará de nuevo.

La app de escritorio DynoTable te permite inspeccionar los Items exactos que tocó una transacción, lo que convierte "¿mi primer intento aterrizó de verdad?" en una consulta en lugar de una conjetura.

Errores relacionados

• TransactionCanceledException — la transacción se ejecutó y se revirtió.
• TransactionConflictException — una transacción concurrente tocó el mismo Item.
• TransactWriteItems: too many items
• Ejemplo de código: TransactWriteItems en Node.js — muestra el uso de ClientRequestToken.
• Aprende: Transacciones de DynamoDB

Referencias

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

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.