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-555555555555Gere 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-Keya 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ê recebe409a 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.