Uma falha de rede depois do envio deixa você sem saber se a mensagem foi criada. Reenviar sem cuidado pode mandar duas mensagens ao mesmo cliente, que é o pior tipo de bug em mensageria. O header Idempotency-Key resolve isso: a Routa garante que a mesma chave produz no máximo uma mensagem.
Onde se aplica
Os demais endpoints de escrita são desenhados para serem seguros de repetir (por exemplo, disable e enable), mas não usam o header. Se você precisa evitar retentativas nesses casos, configure maxRetries: 0 no SDK.
Como usar
Gere uma chave única por mensagem lógica (por exemplo, um UUID v4), antes da primeira tentativa, e envie a mesma chave em todas as retentativas.
Derive a chave de um identificador estável do seu domínio (como o id do pedido e o tipo de aviso). Assim, até um reprocessamento do seu próprio job não duplica a mensagem.
O que acontece em cada caso
No SDK, quando a chamada devolve o resultado de uma tentativa anterior, message._replayed é true.
Escopo e prazo
- A chave vale dentro do projeto, para esta operação. Chaves de projetos diferentes nunca colidem.
- O registro é mantido por 24 horas. Passado esse prazo, repetir a chave executa a operação de novo. A janela serve para retentativas, não para deduplicação permanente.
- A comparação do corpo ignora a ordem das chaves e os espaços do JSON.
Não reutilize uma mesma Idempotency-Key para mensagens diferentes. Uma chave por mensagem lógica, sempre.
Limites da garantia
A idempotência protege a fronteira da API: uma requisição aceita gera exatamente uma mensagem na Routa. Na etapa seguinte, entre a Routa e o WhatsApp, uma falha com resultado desconhecido (como um timeout) é tratada com uma referência determinística enviada ao provedor para deduplicação e com uma consulta de conciliação antes de qualquer nova tentativa. Mesmo assim, não existe entrega exatamente uma vez contra uma API de terceiros: a garantia documentada é pelo menos uma vez, e a Routa torna a duplicidade rara, não impossível. Veja Garantias de entrega. 
