rochasolutions
Back-end

Idempotência em API: Como Evitar Requisição Duplicada

Danilo Rocha5 min de leitura

Um cliente chama POST /pagamentos. A conexão cai antes da resposta chegar. O aplicativo não sabe se o pagamento foi processado ou não, então tenta de novo. Sem nenhum cuidado do lado do servidor, o cliente acaba cobrado duas vezes pela mesma compra.

Isso é o problema que idempotência em API resolve: garantir que repetir uma requisição não repete o efeito dela. Não é um detalhe que só importa em sistema de pagamento. Qualquer rota que cria recurso, cobra algo ou dispara um evento externo corre o mesmo risco a cada timeout de rede.

O Que é Idempotência em uma API

Idempotência em API é a propriedade de uma operação produzir o mesmo resultado, não importa quantas vezes ela seja executada com os mesmos dados. Chamar a rota uma vez ou cinco vezes deixa o sistema exatamente no mesmo estado final.

O conceito vem da matemática, não da web. Aplicado a uma API, ele significa que o segundo POST com o mesmo payload não deveria criar um segundo registro nem cobrar uma segunda vez. O ideal é que o servidor nem precise refazer o trabalho: ele reconhece a requisição repetida e devolve a resposta que já tinha dado antes.

Por Que um Retry de Rede Duplica uma Requisição?

Um retry duplica uma requisição porque o cliente não sabe se a falha aconteceu antes ou depois de o servidor processar o pedido. Timeout, queda de conexão e erro 502 têm a mesma cara para quem chamou: a resposta não chegou. O trabalho, porém, pode já ter sido concluído do outro lado.

Esse é o detalhe que a maioria dos times esquece ao tratar erro de rede. A reação natural é tentar de novo, e isso está certo: é o comportamento esperado do lado do cliente. Quem falha ali é o servidor, por não saber dizer "essa requisição eu já processei" quando ela chega outra vez.

Suponha um app de delivery que perde conexão bem no meio de um POST /pedidos. O app mostra erro e o usuário aperta o botão de novo. Sem proteção nenhuma, dois pedidos idênticos chegam à cozinha, com dois pagamentos cobrados no mesmo cartão.

Quais Métodos HTTP Já São Idempotentes por Natureza

GET, PUT e DELETE já nascem idempotentes pela própria definição do protocolo HTTP. Repetir qualquer um dos três deveria deixar o recurso no mesmo estado, então eles não exigem nenhum cuidado extra na maioria dos casos.

GET só lê, então repetir a chamada não muda nada. PUT substitui o recurso inteiro pelo payload enviado: mandar o mesmo PUT duas vezes grava o mesmo valor duas vezes, sem diferença visível no resultado. DELETE remove o recurso, e chamar DELETE numa coisa que já foi deletada costuma retornar 404 na segunda vez, mas o estado real, recurso inexistente, permanece igual.

POST e PATCH são os verbos problemáticos. POST cria algo novo a cada chamada por definição, e PATCH aplica uma mudança incremental que nem sempre é repetível: incrementar um contador em 1 duas vezes não produz o mesmo resultado que incrementar uma vez só. São esses dois casos que exigem um mecanismo manual de idempotência.

Como Implementar Idempotência com uma Chave

Implementar idempotência em POST e PATCH significa dar ao cliente uma forma de marcar duas tentativas como a mesma operação. O padrão mais usado, o mesmo que a Stripe documenta publicamente na sua API de pagamentos, é o cabeçalho Idempotency-Key.

  1. O cliente gera um identificador único, normalmente um UUID, antes da primeira tentativa.
  2. Toda chamada daquela operação, incluindo os retries, envia o mesmo valor no cabeçalho Idempotency-Key.
  3. O servidor, ao receber a requisição, verifica se já existe uma resposta salva para aquela chave.
  4. Se existir, devolve a resposta salva sem executar a operação de novo.
  5. Se não existir, processa a requisição normalmente e salva o resultado associado à chave antes de responder.

O ponto frágil está no passo 5. Salvar o resultado e processar a operação precisam acontecer de forma atômica, dentro da mesma transação de banco, ou dois retries simultâneos escapam da verificação e executam a operação duas vezes do mesmo jeito.

Onde Guardar a Chave de Idempotência

A chave de idempotência pode morar numa tabela do banco relacional ou num cache de aplicação como Redis, e a escolha depende de quanto tempo a proteção precisa durar. Operação financeira pede a durabilidade do banco. Uma chamada menos crítica aguenta um TTL de minutos em memória.

Uma tabela dedicada, com a chave marcada como única na coluna, aproveita a própria restrição do banco: uma segunda inserção com a mesma chave falha na constraint em vez de depender de uma consulta prévia que pode sofrer condição de corrida. É a forma mais segura quando a operação protegida já envolve uma transação relacional de qualquer jeito, como criar um pedido ou registrar um pagamento.

Redis entrega o resultado mais rápido e encaixa melhor quando a janela de proteção é curta, algo como vinte e quatro horas, e a operação não depende de uma transação relacional. Nos dois casos, vale aplicar a mesma disciplina de expiração que qualquer rate limit de API exige: chave sem TTL nenhum cresce para sempre e um dia estoura a capacidade do armazenamento.

Idempotência em API não aparece na lista de requisitos até o primeiro incidente de cobrança duplicada ou pedido repetido. A partir daí, o cabeçalho Idempotency-Key, uma chave única no banco e um TTL bem calculado resolvem o problema de vez, sem exigir nenhuma mudança no comportamento do cliente que já faz retry.

Se sua API lida com pagamento, pedido ou qualquer operação que não pode duplicar, fale com a gente para revisar os pontos mais frágeis antes que um retry custe caro.