2B Solutions · 14 de outubro de 2026
O problema aparece depois da chamada
Imagine um assistente autorizado a abrir uma solicitação de suporte. Ele chama a API, mas a conexão cai antes de receber a resposta. A solicitação foi criada? Repetir imediatamente parece uma solução simples. Também pode gerar dois registros para o mesmo pedido.
Este é um exemplo hipotético, não um caso de cliente. O ponto é que o problema existe mesmo quando a IA compreende perfeitamente a intenção. Há uma diferença entre decidir o que fazer e executar essa decisão de forma confiável.
O que significa repetir com segurança
Uma operação idempotente pode ser repetida sem acrescentar novos efeitos para a mesma intenção. A Amazon Builders’ Library apresenta essa propriedade como uma forma de tornar novas tentativas mais seguras em sistemas distribuídos. Também descreve a incerteza causada por timeouts: o cliente pode não saber se a operação aconteceu. [1]
Na documentação da Stripe, a chave de idempotência permite reconhecer novas tentativas de uma mesma requisição. Na API v1, após o início da execução, o resultado é armazenado e reutilizado para a mesma chave; parâmetros diferentes podem provocar erro. A documentação também estabelece condições de retenção e diferenças em relação à API v2. Isso mostra por que não devemos presumir que todas as APIs implementam o mesmo contrato. [2]
A identidade da ação precisa sobreviver à tentativa
Nossa recomendação de desenho é separar a operação de negócio das tentativas de envio. A aplicação atribui um identificador estável à operação autorizada e guarda seu estado. Uma nova tentativa dessa mesma operação reutiliza a identidade; uma nova intenção legítima recebe outra identidade.
No exemplo do suporte, dois cliques acidentais para abrir o mesmo chamado devem ser distinguidos de dois chamados realmente diferentes. Comparar apenas o texto não basta como regra de negócio: pessoas podem fazer solicitações legítimas com descrições iguais.
A chave também não deve funcionar como senha nem carregar dados pessoais. A Stripe recomenda evitar informações sensíveis, como e-mails e identificadores pessoais, nesse campo. [2]
Um fluxo prático para um protótipo
Considere esta proposta de implementação, a adaptar ao contrato de cada integração:
Valide a intenção, os parâmetros e a autorização antes de executar.
Registre a operação e seu identificador estável antes do envio.
Use o mecanismo de idempotência do destino, quando ele existir, e associe o recibo externo à operação local.
Se a resposta não chegar, mantenha um estado explícito de resultado desconhecido. Consulte o destino ou reconcilie os registros antes de decidir por nova tentativa.
Apresente ao usuário o estado comprovado: concluído, em verificação ou falhou. Não transforme ausência de resposta em confirmação de sucesso.
Um registro local, isoladamente, não garante ausência de duplicação no serviço externo. A proteção precisa considerar o destino, a concorrência entre trabalhadores e a janela de validade da chave. Sem um mecanismo confiável de consulta ou deduplicação, a revisão humana pode ser necessária.
Teste a falha, não apenas o caminho feliz
Em ambiente de testes, simule três situações: a resposta se perde depois da criação; dois trabalhadores enviam a mesma operação simultaneamente; uma repetição chega depois da expiração da chave.
Para cada situação, registre quantos efeitos ocorreram no destino, qual estado ficou no sistema e o que o usuário viu. Inclua também uma nova solicitação legítima com conteúdo igual: ela deve continuar possível. A meta do exercício é demonstrar comportamento correto, não prometer uma taxa de melhoria sem medição.
Antes de dar mais autonomia
Escolha uma única ação de baixo risco e documente sua política de repetição. Quem cria a identidade? Quando ela expira? Como verificar o resultado? Quando interromper e encaminhar para análise?
Agentes úteis precisam de boas decisões e de execução previsível. A próxima melhoria da sua automação pode estar nessa fronteira entre a intenção e o efeito.
Fontes primárias
[1] AWS, Amazon Builders’ Library — Making retries safe with idempotent APIs, Malcolm Featonby. https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
[2] Stripe — Idempotent requests. https://docs.stripe.com/api/idempotent_requests
Fontes consultadas em 14/10/2026. As páginas consultadas não exibiram data editorial confiável de publicação/atualização no trecho utilizado. Conteúdo técnico explicativo, não anúncio de lançamento. O fluxo e os testes propostos são recomendações editoriais originais.