Idempotência

Idempotência na API

A idempotência é uma propriedade que garante que realizar a mesma operação múltiplas vezes terá o mesmo efeito que realizá-la apenas uma vez. Em sistemas distribuídos, ela é essencial para evitar efeitos colaterais indesejados (como cobranças duplicadas ou criação de registros repetidos) em casos de falhas de rede ou retentativas (retries).

Por que utilizar?

Imagine que um cliente envia uma requisição para processar um pedido, mas a conexão cai antes de receber a confirmação:

1. O cliente não sabe se o pedido foi processado.
2. Sem idempotência, se o cliente tentar novamente, ele pode ser criado o pedido duas vezes.
3. Com idempotência, o servidor reconhece a tentativa repetida e apenas retorna o resultado da transação original.

Implementação via Idempotency-Key

Para garantir que operações de escrita (especialmente POST) sejam seguras, utilizamos o cabeçalho personalizado Idempotency-Key.

Como funciona:

1. Geração da Chave: O cliente gera um identificador único para a operação, que pode ser um UUID ou qualquer outro identificador de sua preferência.
2. Envio: O cliente envia a requisição incluindo o cabeçalho: Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
3. Processamento:
   1. Se for a primeira vez: O servidor processa a lógica, armazena o resultado em cache e retorna a resposta.
   2. Se a chave for repetida: O servidor ignora o re-processamento e retorna instantaneamente a resposta que está no cache.
      1. Se ocorrer tentativa de processar a mesma chave simultaneamente por múltiplas threads, a requisição concorrente irá receber o erro 409 Conflict.
   3. Se você enviar a mesma chave de idempotência, mas com um corpo (payload) diferente, o servidor retornará um erro 422 Unprocessable Entity para evitar inconsistência de dados.

Tempo de Vida (TTL): As chaves de idempotência expiram após 24 horas. Após esse período, uma nova tentativa com a mesma chave será tratada como uma nova requisição.

Escopo: A chave de idempotência deve ser informada apenas em endpoints que estejam mapeadas na documentação.