O que é idempotência, e como as idempotency keys tornam os retries seguros?

Question

IT Interview Practice · Accepted Answer

**Idempotência** significa que realizar uma operação **múltiplas vezes tem o mesmo efeito que realizá-la uma vez**. Isso importa porque as redes são não confiáveis: quando um client envia um request e a response nunca chega, ele não consegue saber se o server o processou. Se ele refizer (retry), uma operação não idempotente pode rodar duas vezes.

## O problema

```text
Client ──POST /payments {$100}──▶ Server   (cobra $100 ✓)
Client ◀────────X (timeout)────── Server   (response perdida)
Client ──POST /payments {$100}──▶ Server   (cobra $100 DE NOVO ✗ → $200!)
```

`GET`, `PUT`, e `DELETE` são naturalmente idempotentes, então refazê-los é seguro. `POST` **não** é — é exatamente daí que vêm cobranças duplicadas e pedidos duplicados.

## A solução: idempotency keys

O client gera uma **chave única** (geralmente um UUID) para a operação lógica e a envia em um header. O server armazena a chave junto com o resultado; se a mesma chave chegar de novo, ele retorna o resultado **armazenado** em vez de reexecutar.

```http
POST /payments HTTP/1.1
Idempotency-Key: 5f2b8c1e-3a4d-4e6f-9c0b-1a2b3c4d5e6f
Content-Type: application/json

{ "amount": 100, "currency": "usd" }
```

```text
Lógica do server ao receber um request com uma Idempotency-Key:
  1. Procurar a chave em um store (ex. Redis/DB).
  2. Se encontrada → retornar a response salva (sem cobrar de novo).  ← o caso de retry
  3. Se não       → processar, salvar (chave → response), e retornar.
  (Envolva o passo 3 em uma transação / lock para retries concorrentes não executarem duas vezes.)
```

A **mesma chave** no retry produz o mesmo `200` e o mesmo pagamento — o cliente é cobrado uma vez. É exatamente assim que a API do Stripe funciona.

## Por que isso importa

Esta pergunta separa os engenheiros que projetam para o happy path daqueles que projetam para a **falha**, que é do que se trata a confiabilidade em produção. Sistemas distribuídos garantem que timeouts e falhas parciais *vão* acontecer, então qualquer endpoint com side effects — pagamentos, pedidos, envio de dinheiro — precisa de uma estratégia de retry, e "apenas refazer" é perigoso para `POST`. O entrevistador quer ouvir o insight em duas partes: primeiro, que a idempotência é uma propriedade que você pode *projetar de propósito* (tornando `PUT`/`DELETE` naturalmente seguros, e dando ao `POST` uma **idempotency key** quando ele não pode ser), e segundo, o detalhe sutil de concorrência — dois retries chegando ao mesmo tempo não podem ambos executar, então a checagem da chave e a escrita precisam de um lock ou de uma unique constraint. Acertar isso é a diferença entre cobrar um cliente uma vez e cobrá-lo duas, e é por isso que toda API séria de pagamentos e comércio o implementa.

O problema

A solução: idempotency keys

Por que isso importa

Perguntas relacionadas