Evitando duplicidade (Idempotency-Key)

Se a sua ferramenta reenvia automaticamente em caso de timeout, use este cabeçalho — é exatamente o cenário em que dois registros iguais nascem sem ninguém p…

Se a sua ferramenta reenvia automaticamente em caso de timeout, use este cabeçalho — é exatamente o cenário em que dois registros iguais nascem sem ninguém perceber.

Idempotency-Key: 11111111-2222-4333-8444-555555555555

Gere um UUID novo por operação. Não reaproveite o mesmo valor entre operações diferentes.

O valor é texto livre de até 255 caracteres — UUID é a recomendação, não uma exigência. Passar de 255 devolve 400.

Aceitam o cabeçalho: criação de contato, empresa, negócio, tarefa, anotação (das três entidades), funil, etapa de funil, compromisso de agenda, webhook, teste de webhook, e os envios em lote. Em produtos: criar (inclusive em lote), editar e excluir produto, criar categoria, e adicionar/editar/remover/substituir linhas de produto do negócio — reenviar um DELETE já concluído com a mesma chave devolve a mesma resposta (não 404), e ?dry_run=true não consome a chave.

⛔ É obrigatório em POST/api/conversations/{id}/messages — sem ele, 400. É a única operação cujo efeito sai do sistema e chega a uma pessoa de verdade no WhatsApp: um reenvio por engano duplica a mensagem para o seu cliente, não um registro no seu banco.

Situação O que acontece
1ª chamada Executa normalmente e guarda a resposta
Reenvio, mesma chave, mesmo corpo Devolve a mesma resposta, com o cabeçalho idempotent-replay: true. Nada é executado de novo
Reenvio, mesma chave, corpo diferente 409 conflict — a chave identifica a operação, não só o cabeçalho
Reenvio enquanto a 1ª ainda está rodando 409 conflict — aguarde e reenvie
Mesma chave em outra rota, método ou registro 409 conflict
Mesma chave usada por outra chave de API Sem efeito — cada chave de API tem seu próprio espaço
A 1ª chamada morreu no meio Após 2 minutos a chave é liberada e o reenvio executa
A chamada terminou em erro A chave é liberada: corrija e reenvie com a mesma
Erro com x-salos-partial-write: true (produtos) A chave não é liberada: o reenvio devolve o mesmo erro e não grava de novo o que já entrou

As chaves ficam guardadas por 24 horas.

A armadilha mais comum em n8n e Zapier. É natural amarrar o Idempotency-Key a uma expressão do fluxo ({{$execution.id}}) sem perceber que o valor fica constante em todas as iterações do laço. Se cada iteração manda um corpo diferente com a mesma chave, você recebe 409 a partir da segunda. Gere um UUID novo por item, não por execução do fluxo.

Alguns POST ignoram o cabeçalho porque já são idempotentes por natureza: criar tag com nome repetido devolve a existente, aplicar tag é um vínculo único, e POST/api/leads tem o external_ref.