O problema real: retries criam duplicidade (e você só descobre no financeiro)
Na automação, falha “bonita” é rara. O mais comum é: a API demora, o cliente dá timeout, o workflow faz retry, e a mesma criação de pedido roda duas vezes. Em integrações com pagamento, isso vira estorno, chargeback e suporte.
Idempotência não impede falhas; ela impede que a recuperação da falha (retry) gere um efeito colateral a mais.
O que é Idempotency-Key na prática (e o que NÃO é)
Na prática, é uma string (por exemplo um UUID) que representa uma tentativa lógica de operação. Se a mesma chave for reenviada, o servidor deveria responder de forma consistente: ou retorna o resultado já criado, ou informa que aquela operação já foi processada.
Não confunda com deduplicação “por conteúdo” (comparar payload), nem com "id" do recurso final. A chave de idempotência é do ato de pedir para criar, não do objeto criado.
| Conceito | Serve para | Exemplo rápido | Risco se usado errado |
|---|---|---|---|
| Idempotency-Key | Reenvio seguro do mesmo POST | Header Idempotency-Key: 6f... (repetido nos retries) | Se mudar a chave a cada retry, duplica do mesmo jeito |
| Id do recurso | Identificar o objeto criado | pedidoId=123 | Não evita duplicidade se dois pedidos diferentes forem criados |
| Hash do payload | Detectar payloads iguais | sha256(body) | Pode bloquear operações legítimas iguais (2 compras iguais) |
| Lock/Mutex | Garantir exclusão mútua | lock por cliente | Pode virar gargalo e travar fila inteira |
Onde a chave vive: no header, no banco e no seu desenho de fluxo
O “padrão de mercado” (quando existe) é enviar a chave no header. Várias APIs de pagamento e billing aceitam isso, mas cada uma define detalhes: tempo de retenção, se a resposta é a mesma, e quais campos entram no escopo da idempotência. Sem internet aqui, então trate como regra geral: leia a doc do endpoint específico.
Quando a API não suporta Idempotency-Key, você ainda consegue idempotência do lado do workflow: persistindo a chave + status em um banco e bloqueando reprocessamento.
Como implementar em automações (n8n/Make/Zapier): um roteiro sem romantismo
Você não precisa “feature nativa” para ter idempotência. Precisa de disciplina: chave estável + armazenamento + checagem antes de executar.
Em ferramentas de automação, o ponto crítico é: o retry pode acontecer sem você ver (timeout, rate limit, falha intermitente). Então a idempotência tem que estar antes do nó que cria/cobra/emite.
Armadilhas comuns (as que mais dão dor de cabeça)
Idempotência costuma falhar não por falta de conceito, mas por detalhe de implementação. E detalhe em automação vira duplicidade em produção.
Se você lembrar de duas coisas: (1) chave não pode mudar no retry; (2) armazenamento precisa ser confiável e consultado antes do efeito colateral.
Checklist rápido: quando vale o esforço
Se a operação custa dinheiro, gera obrigação fiscal ou cria estado difícil de desfazer, a resposta é: vale. Se é uma atualização idempotente por natureza (PUT com o mesmo estado final), às vezes você já está coberto sem perceber.
| Tipo de ação | Sem Idempotency-Key | Com Idempotency-Key |
|---|---|---|
| Criar cobrança/fatura | Risco alto de duplicar em retry | Retry seguro (mesma operação) |
| Criar pedido | Pedidos duplicados e reconciliação manual | Reenvio retorna o mesmo resultado |
| Enviar e-mail | E-mails repetidos (ruim, mas reversível) | Evita duplicar se você controlar por chave |
| Atualizar status (PUT) | Muitas vezes já é idempotente | Geralmente opcional, depende do endpoint |
Perguntas frequentes
Idempotency-Key é obrigatório para toda API?
Posso usar o mesmo Idempotency-Key para várias operações diferentes?
Se a API não suporta Idempotency-Key, ainda dá para evitar duplicidade?
Idempotency-Key substitui validação de assinatura de webhook (HMAC)?
Termos relacionados
Como fazer idempotência em automações com webhook (e parar de duplicar pedidos, notas e leads)
Guia direto para aplicar idempotência em automações com webhook: chaves idempotentes, deduplicação, banco/planilha, retries e boas práticas para n8n/Make/Zapier.
Ler →
Como evitar replay attack em webhooks: timestamp, nonce e idempotência (na prática)
Guia prático para proteger webhooks contra replay attack usando timestamp, nonce, verificação de assinatura e idempotência. Com passos, checklist e exemplos de decisões para automações (n8n/Make/Zapier).
Ler →
Webhook ou polling em automações: como escolher (sem perder eventos e sem estourar limites)
Guia direto para decidir entre webhook e polling: latência, confiabilidade, custo por execução, rate limit e como evitar duplicidades. Inclui tabela e checklist prático.
Ler →
Erro 429 (Rate Limit) em automações: como resolver sem travar o fluxo
Entenda o que causa o erro 429 (rate limit), como calcular limites, aplicar retry com backoff, filas e idempotência para automações com API que não quebram em pico.
Ler →