O que é Chave de idempotência?

O que é uma chave de idempotência

Chave de idempotência é um identificador usado por uma API para relacionar várias tentativas à mesma ação. Você gera ou obtém a chave antes da chamada e a preserva quando repete aquela ação, conforme o contrato oferecido pelo servidor.

Ela é útil quando a aplicação perde a resposta e não sabe se o destino concluiu uma criação. Uma nova tentativa com a mesma chave pode ser reconhecida como repetição, permitindo recuperar o resultado sem criar outro registro, desde que o serviço implemente esse comportamento.

A chave pertence à ação, não a cada tentativa

Imagine uma solicitação de exportação identificada como exp-824. A primeira chamada e seu retry pertencem à mesma solicitação, enquanto uma nova exportação feita depois representa outra ação e precisa de sua própria identidade.

Gerar uma chave nova toda vez que a rede falha elimina essa associação. O servidor pode tratar cada tentativa como uma criação diferente, mesmo que o corpo contenha os mesmos campos.

O contrato define o reconhecimento

Algumas APIs recebem a chave em um header, como Idempotency-Key, enquanto outras usam um parâmetro próprio. Confira onde o identificador deve ser enviado e qual é seu escopo, pois o reconhecimento pode depender do endpoint, da credencial ou de outra associação definida pelo serviço.

O destino também pode comparar o conteúdo das tentativas. Na Stripe, reutilizar uma chave com parâmetros diferentes pode gerar erro, evitando que uma atualização diferente seja confundida com a chamada original.

Duas tentativas simultâneas exigem um comportamento definido para a ação ainda em processamento. Você não deve presumir que ambas receberão imediatamente uma resposta idêntica, já que a API pode informar conflito ou exigir nova consulta enquanto a primeira chamada não termina.

A retenção limita por quanto tempo a chave é reconhecida

O serviço pode remover o registro de uma chave depois do período documentado. Reutilizar esse valor após a remoção pode produzir uma nova ação, por isso uma tarefa recuperada muito tempo depois exige consultar o destino e conferir a validade da associação.

O registro do resultado também depende de a API ter iniciado o processamento. A Stripe documenta condições nas quais a execução nem começa e o resultado idempotente não é registrado, como falhas de validação anteriores ao processamento.

Identificar a ação não concede acesso

A chave não substitui a credencial que autoriza a chamada. Ela deve identificar a solicitação sem carregar senhas ou informações pessoais desnecessárias, e precisa ficar disponível para a aplicação recuperar a tentativa depois de uma interrupção.

A idempotência também pode existir sem esse tipo de chave, como em uma atualização que define um valor fixo. O identificador é um mecanismo possível para implementar a propriedade, não sua definição.

Como conferir a integração

Em um ambiente de teste, envie a mesma ação com a mesma chave e compare o identificador e o estado do recurso no destino. Verifique também a resposta para parâmetros diferentes, repetição simultânea e recuperação após o prazo de retenção documentado.

O resultado deve demonstrar que tentativas da mesma ação permanecem associadas e que ações distintas recebem identidades próprias. Apenas ver o header na chamada não comprova que o servidor o reconheceu.

Aplicação na formação

n8n Experts

A chave de idempotência permite reconhecer tentativas da mesma ação quando o serviço oferece esse mecanismo.

Conhecer a formação →