técnico · resposta com fontes
Chave de idempotência: como evitar envios duplicados de e-mail
Uma chave de idempotência é um valor único gerado pelo cliente e enviado em uma requisição de API para garantir que uma operação seja executada exatamente uma vez. Se uma requisição for repetida com a mesma chave, o servidor reconhece a duplicata e retorna a resposta original sem processar a ação novamente.
Funcionamento técnico
Quando um cliente envia uma requisição com uma chave de idempotência, o servidor armazena a chave e a resposta resultante em um cache. Se uma requisição seguinte chegar com a mesma chave, o servidor pula a lógica de execução e simplesmente retorna a resposta em cache. Esse mecanismo é fundamental em sistemas distribuídos, nos quais timeouts de rede podem deixar o cliente sem saber se a requisição chegou ao servidor.
Importância para remetentes
No e-mail transacional, enviar a mesma mensagem duas vezes pode gerar uma experiência ruim para o usuário e mais denúncias de spam. As chaves de idempotência permitem que os desenvolvedores implementem uma lógica agressiva de novas tentativas para chamadas de rede que falharam, sem o risco de enviar e-mails duplicados ao destinatário. Isso garante confiabilidade e consistência em todo o pipeline de entrega.
Considerações operacionais
As chaves devem ser geradas com um UUID ou uma string aleatória de alta entropia para evitar colisões. Os servidores normalmente expiram essas chaves após 24 horas. Os desenvolvedores precisam garantir que a chave esteja vinculada à intenção específica da mensagem: alterar o corpo do e-mail ou o destinatário mantendo a mesma chave deve resultar em erro, e não em um sucesso vindo do cache.
Exemplo de implementação
Uma aplicação SaaS gera uma chave única para um e-mail de redefinição de senha. A aplicação chama a API de e-mail, mas a conexão cai antes de a resposta chegar. A aplicação repete a requisição usando a mesma chave. A API vê que a chave já existe e retorna 200 OK sem enviar um segundo e-mail ao usuário. As ferramentas gratuitas do SendHQ ajudam os desenvolvedores a gerenciar a infraestrutura de e-mail com eficiência.
Tratamento de erros
Se uma requisição for modificada, mas enviada com uma chave de idempotência já existente, o servidor deve retornar um erro de conflito. Isso evita a reutilização acidental de chaves para mensagens diferentes. O tratamento adequado consiste em capturar esses conflitos e gerar uma nova chave para o payload da requisição atualizada.
Perguntas que as equipes fazem
Chave de idempotência é a mesma coisa que ID da mensagem?
Não. O ID da mensagem é atribuído pelo servidor após o processamento, enquanto a chave de idempotência é atribuída pelo cliente antes de a requisição ser enviada.
O que acontece se a chave de idempotência expirar?
Se a chave expirar do cache do servidor, uma nova tentativa será tratada como uma nova requisição, o que pode resultar no envio de um e-mail duplicado.
Qual tipo de dado é melhor para chaves de idempotência?
O UUID v4 é o padrão do setor, porque oferece uma probabilidade de colisão desprezível em sistemas distribuídos.
Fontes primárias
- SendGrid Documentation — Twilio SendGrid (em inglês)
- Postmark Developer Documentation — Postmark (em inglês)