DynamoDB IdempotentParameterMismatchException

TL;DR — Você chamou TransactWriteItems com um ClientRequestToken que já foi usado nos últimos 10 minutos, mas o resto da requisição mudou. O token promete "esta é a mesma transação, repetida" — então o DynamoDB rejeita a reutilização de um token cujo payload difere. Reutilize o token apenas para retries byte-idênticos; cunhe um token novo (um UUID) para toda nova transação lógica.

O que 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 torna o TransactWriteItems idempotente: múltiplas chamadas idênticas com o mesmo token têm o efeito de uma única chamada, o que te protege de aplicar uma transação em dobro quando um timeout esconde se a primeira tentativa aterrissou. Um token permanece válido por 10 minutos após a primeira requisição que o usou completar. Se uma requisição chega dentro dessa janela com o mesmo token mas parâmetros diferentes, o DynamoDB não pode tratá-la como um retry — e se recusa a tratá-la como uma nova transação também. HTTP 400, não retentável como está.

Por que acontece

• Um token estático ou hardcoded — a mesma string de token é enviada para toda transação, então a segunda transação (diferente) colide com a primeira.
• Token derivado de algo grosseiro demais — por exemplo, o ID do usuário ou o nome da tabela, então duas transações diferentes para o mesmo usuário compartilham um token.
• O retry reconstruiu a requisição de forma diferente — um timestamp, valor de TTL ou ID gerado dentro de um item mudou entre a tentativa um e o retry, então a "mesma" transação não corresponde mais byte a byte.
• Dois caminhos de código compartilham uma fonte de token — workers paralelos semeados com o mesmo valor.

Como corrigir

1. Gere um token único por transação lógica — um UUID no ponto onde a transação é composta:

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

2. Mantenha o token com a requisição ao tentar novamente — repita o mesmo objeto de requisição já construído, não um reconstruído, para que nada no payload possa desviar. (Os AWS SDKs fazem isso corretamente para seus retries automáticos; o bug é quase sempre um retry no nível da aplicação que recompõe a requisição.)

3. Fixe valores voláteis antes de compor — timestamps e IDs gerados precisam ser computados uma vez e reutilizados no retry, não reavaliados.

4. Não reutilize um token após 10 minutos esperando idempotência — passada a janela, a requisição é tratada como totalmente nova e será aplicada novamente.

O app desktop DynoTable permite inspecionar os itens exatos que uma transação tocou, o que torna "minha primeira tentativa de fato aterrissou?" uma busca em vez de um palpite.

Erros relacionados

• TransactionCanceledException — a transação rodou e foi revertida.
• TransactionConflictException — uma transação concorrente tocou o mesmo item.
• TransactWriteItems: too many items
• Exemplo de código: TransactWriteItems in Node.js — mostra o uso de ClientRequestToken.
• Aprenda: DynamoDB transactions

Referências

• 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 pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.