Skip to main content

O que é idempotência?

Uma requisição idempotente pode ser enviada múltiplas vezes com o mesmo resultado — sem criar duplicatas ou causar efeitos colaterais indesejados. Isso é essencial para lidar com falhas de rede, timeouts e retentativas.

Como usar

Inclua o header Idempotency-Key em requisições POST com um UUID v4 único gerado pelo seu sistema:
Se você enviar a mesma requisição com a mesma Idempotency-Key novamente, a API retorna a resposta original em cache — sem criar um novo recurso.

Comportamento

Prazo de validade

As chaves de idempotência têm validade de 24 horas. Após esse período, a mesma chave pode ser reutilizada para uma nova operação.

Exemplo: criação segura de contato

Boas práticas

  • Gere a chave antes de iniciar a operação — não após uma falha
  • Armazene a chave junto com a operação — para poder reutilizá-la em retentativas
  • Use UUID v4 — evite chaves previsíveis ou sequenciais
  • Uma chave por operação lógica — não reutilize a mesma chave para operações diferentes