TransactionInProgressException

TL;DR — Um retry de TransactWriteItems carregou o mesmo ClientRequestToken de uma tentativa que ainda está executando. Isso normalmente é seu cliente expirando mais rápido do que a transação completa, então o retry do SDK colide com a original em andamento. Continue tentando com backoff — um retry posterior após a original terminar retorna o sucesso idempotente — e ajuste os timeouts para que ao menos um retry aterrisse após ~5 segundos.

O que significa

TransactionInProgressException: The transaction with the given request token
is already in progress.

O ClientRequestToken torna o TransactWriteItems idempotente: chamadas idênticas dentro de uma janela de 10 minutos contam como uma transação. Enquanto a primeira tentativa ainda está sendo processada, uma segunda chamada com o mesmo token ainda não pode ser respondida — não é nem uma duplicata de uma transação concluída nem uma nova — então o DynamoDB a rejeita com esta exceção. É um sinal de tempo, não um erro de dados.

Por que acontece

• Timeout do cliente mais curto que a latência da transação — o timeout da requisição dispara, o SDK tenta novamente, e o retry chega enquanto a transação original ainda está commitando.
• Política de retry agressiva — backoff muito curto significa que vários retries podem se empilhar em uma transação que precisa de alguns segundos.
• Dois chamadores compartilhando um token — processos separados deliberadamente (ou acidentalmente) emitindo o mesmo ClientRequestToken concorrentemente.

Como corrigir

1. Deixe os retries continuarem com backoff exponencial — uma vez que a transação em andamento completa, um retry com o mesmo token retorna sucesso sem aplicar as escritas duas vezes. Trate esta exceção como retentável.

2. Ajuste os timeouts conforme a orientação documentada para que um retry possa aterrissar após a transação estabilizar:

   • permita ao menos um retry ser processado após 5 segundos terem passado desde a primeira tentativa;
   • defina o timeout por requisição para cerca de 1 segundo ou mais;
   • mantenha o socket timeout ligeiramente abaixo do request timeout;
   • use backoff exponencial entre tentativas.

3. Não rotacione o token no retry — gerar um novo ClientRequestToken por tentativa silenciosamente converte retries em novas transações (aplicando as escritas duas vezes). Mesma intenção, mesmo token, por até 10 minutos:

   const token = randomUUID(); // one token per logical transaction
   await client.send(new TransactWriteItemsCommand({TransactItems, ClientRequestToken: token}));

4. Serialize chamadores concorrentes deliberados — se dois workers podem submeter a mesma transação lógica, faça um deles o dono ou roteie ambos por uma fila.

Se as transações rodam tempo suficiente para disparar timeouts, verifique no que estão disputando — o app desktop DynoTable permite inspecionar os itens envolvidos, e a calculadora de preços do DynamoDB mostra quanto custa a capacidade de escrita dobrada das escritas transacionais.

Erros relacionados

• IdempotentParameterMismatchException — mesmo token, payload diferente.
• TransactionCanceledException — a própria transação falhou.
• TransactionConflictException — conflito no nível de item com outra transação.
• Exemplo de código: TransactWriteItems in Node.js — mostra o uso de ClientRequestToken.
• Aprenda: DynamoDB transactions

Referências

• TransactWriteItems — Amazon DynamoDB API Reference
• Amazon DynamoDB Transactions: How it works — Amazon DynamoDB Developer Guide
• 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.