Chave de idempotência

Definição

Chave de idempotência é um identificador que reconhece tentativas da mesma operação segundo um contrato definido. Você associa um valor estável às tentativas, e o serviço usa esse valor para reconhecer a operação lógica. A estabilidade do valor é o que permite distinguir uma repetição de uma operação nova.

Como o serviço reconhece a chave

Quando uma chamada chega com uma chave, o serviço confere se essa chave já apareceu antes. Se apareceu, ele retoma o resultado registrado e associa a nova tentativa à operação original em vez de executar outro efeito. O resultado da primeira tentativa é devolvido de novo, e o estado permanece igual ao que foi criado no início.

Cuidados na implementação

Gerar outra chave em cada retry perde a associação entre as tentativas. Além disso, a validade da chave e o comportamento diante de expiração dependem do serviço, e o fluxo precisa tratar essas duas situações. Uma chave expirada pode permitir um novo efeito, e você precisa saber o que o serviço faz nesse caso antes de repetir a chamada.

Colisão de chaves e verificação

A falha comum é reutilizar a mesma chave para operações distintas: o serviço reconhece a segunda chamada como repetição da primeira e não executa a operação nova. Para verificar, registre o identificador junto de cada tentativa e confira o resultado devolvido. Quando duas chamadas com a mesma chave descrevem efeitos diferentes, o valor não está estável por operação, e a conferência do efeito no destino mostra se a associação está correta.

Aplicação na formação

n8n Experts

Na formação n8n Experts, a chave de idempotência protege operações repetidas em fluxos com retry e webhooks.

Conhecer a formação →