Pular para o conteúdo
Setup do Dev
Desenvolvimento

Idempotência em APIs: como evitar a cobrança em dobro quando a rede falha

A requisição de pagamento caiu e você não sabe se ela chegou. A chave de idempotência, como a Stripe usa e como implementar no seu backend com PostgreSQL.

Por Setup do Dev
6 min de leitura
Compartilhar
Capa do Setup do Dev em azul de planta técnica: "Uma cobrança, mesmo com a rede caindo", com duas requisições POST com a mesma Idempotency-Key, a primeira cobrada e a segunda devolvendo a resposta guardada

O cliente toca em “Pagar”. A tela fica girando, o 4G oscila, aparece um erro de conexão. Ele toca de novo. Do lado do servidor, a pergunta que decide se a empresa vai receber uma reclamação no dia seguinte é simples: a primeira requisição chegou ou não chegou? Se chegou, a segunda é uma cobrança em dobro.

A resposta para isso tem nome, idempotência, e uma implementação conhecida, a chave de idempotência. A Stripe explicou o padrão num texto de 2017 escrito por Brandur Leach, e ele continua sendo a base da API de pagamentos dela hoje. Este guia junta as duas coisas e mostra uma implementação mínima, com SQL testado no PostgreSQL.

Os três jeitos de uma chamada falhar

O texto da Stripe separa as falhas de rede em três casos. Na primeira, a conexão nem chega a ser aberta: o servidor nunca soube da requisição, e tentar de novo é seguro. Na segunda, a chamada cai no meio do processamento, com parte do trabalho feita. Na terceira, o servidor terminou tudo, e a conexão caiu antes de a resposta voltar.

Nos dois últimos casos, o cliente não tem como saber o que aconteceu. Para uma consulta, tanto faz: repete e pronto. Para uma cobrança, um cadastro ou um envio de e-mail, repetir sem cuidado faz a mesma coisa duas vezes.

O que é uma operação idempotente

Idempotente é a operação que pode ser repetida sem mudar o resultado depois da primeira vez. O RFC 9110, que define a semântica do HTTP, lista os métodos idempotentes por definição: GET, HEAD, OPTIONS, TRACE, PUT e DELETE. Apagar o mesmo recurso duas vezes deixa o sistema no mesmo estado que apagar uma.

O POST fica de fora, e é justamente o método das operações que mais doem: criar uma cobrança, um pedido, um usuário. É para ele que existe a chave de idempotência.

Homem segurando um cartão de crédito diante do notebook, numa mesa de escritório
Foto: Matt Moloney / StockSnap (licença CC0)

A chave de idempotência

A ideia é o cliente gerar um identificador único para cada operação e mandar junto com a requisição. Na Stripe, ele vai no cabeçalho Idempotency-Key. O servidor associa a chave ao resultado da primeira execução. Se a mesma chave chegar de novo, ele não executa outra vez: devolve o resultado guardado.

A documentação atual da Stripe detalha as regras da API v1, e elas servem de bom modelo para qualquer API:

  • a chave pode ter até 255 caracteres, e a recomendação é usar um UUID versão 4 ou outra sequência aleatória com entropia suficiente para não colidir;
  • a chave não deve carregar dado sensível, como e-mail ou documento do cliente;
  • o servidor guarda o código de status e o corpo da primeira resposta, inclusive quando ela foi um erro 500;
  • as chaves podem ser descartadas depois de pelo menos 24 horas, e uma chave reaproveitada depois disso vira uma requisição nova;
  • se a mesma chave chegar com parâmetros diferentes, a API devolve erro, para pegar o uso acidental;
  • se a requisição falhou na validação, ou conflitou com outra igual em andamento, nada é guardado, e dá para tentar de novo.

A documentação ainda avisa que mandar a chave em GET e DELETE não tem efeito, porque eles já são idempotentes.

Como implementar no seu backend

A versão mínima cabe numa tabela com a chave como chave primária. É a restrição do banco, e não um if no código, que impede duas execuções da mesma operação, inclusive quando as duas tentativas chegam ao mesmo tempo:

CREATE TABLE chaves_idempotencia (
  chave        text PRIMARY KEY,
  hash_pedido  text NOT NULL,
  status       int,
  resposta     jsonb,
  criada_em    timestamptz NOT NULL DEFAULT now()
);

Ao receber a requisição, o servidor tenta reservar a chave:

INSERT INTO chaves_idempotencia (chave, hash_pedido)
VALUES ($1, $2)
ON CONFLICT (chave) DO NOTHING
RETURNING chave;

Se o INSERT devolveu a chave, é a primeira vez: o servidor executa a operação e, no fim, grava o status e a resposta na mesma linha. Se não devolveu nada, a chave já existia. Aí ele lê a linha e compara o hash_pedido: se o corpo é o mesmo, devolve a resposta guardada; se é diferente, responde com erro, como a Stripe faz.

Rodamos esse fluxo no PostgreSQL 18: a primeira tentativa reserva a chave, a segunda não insere nada, e a consulta devolve o status 201 e o corpo gravados na primeira. Falta tratar um caso: a chave reservada e ainda sem resposta, quando a primeira tentativa está em andamento ou morreu no meio. A saída mais simples é responder com um erro de conflito e deixar o cliente tentar de novo um pouco depois, que é o mesmo comportamento descrito pela Stripe para requisições concorrentes.

Se a operação inteira roda dentro de uma transação no mesmo banco, o caso da queda no meio fica fácil: a transação desfeita leva junto a reserva da chave, e a nova tentativa começa do zero. O cuidado é com o que sai do banco, como a chamada ao gateway de pagamento ou o envio de e-mail, que não volta com o ROLLBACK.

Pessoa de camisa azul trabalhando num computador de mesa com código na tela
Foto: Lee Campbell / StockSnap (licença CC0)

Do lado do cliente: tentar de novo com calma

A chave torna a nova tentativa segura. O texto da Stripe acrescenta como ela deve ser feita: com espera exponencial, em que o intervalo cresce em proporção a 2 elevado ao número de falhas, e com um componente aleatório no tempo de espera, o jitter. Sem ele, milhares de clientes que falharam juntos voltam juntos, no mesmo segundo, e derrubam de novo o servidor que estava se recuperando. É o problema conhecido como thundering herd.

Para a chamada que falha sempre, a espera não basta: aí entra o circuit breaker, o padrão que para de insistir num serviço fora do ar.

Os erros mais comuns

O primeiro é gerar a chave a cada tentativa, e não a cada operação. A chave nasce quando o usuário toca em “Pagar” e é reaproveitada em todas as novas tentativas daquele pagamento; uma chave nova por tentativa anula o mecanismo inteiro. O segundo é guardar a chave só na memória do aplicativo: se o app fecha no meio, a nova tentativa sai com outra chave. O terceiro é usar dado do cliente como chave, o que a própria Stripe desaconselha.

Na prática, quem integra com a Stripe tem boa parte disso pronta: as bibliotecas oficiais sabem enviar a chave e repetir a requisição sozinhas (vale conferir na documentação da sua linguagem se a nova tentativa automática está ligada). Quem escreve a própria API de pedidos, cobrança ou cadastro precisa construir o mesmo mecanismo, e a tabela acima é um bom ponto de partida.

Fontes: Stripe Blog: Designing robust and predictable APIs with idempotency, Stripe Docs: Idempotent requests, RFC 9110, seção 9.2.2

Produzido com auxílio de IA e revisado pela redação.

Comentários (0)

Ainda não há comentários. Comece a conversa.

Deixe seu comentário

Seu e-mail não será publicado. O primeiro comentário de cada pessoa passa por moderação.

Seja respeitoso

Neste artigo

  1. Os três jeitos de uma chamada falhar
  2. O que é uma operação idempotente
  3. A chave de idempotência
  4. Como implementar no seu backend
  5. Do lado do cliente: tentar de novo com calma
  6. Os erros mais comuns

Mais lidas

Editorias

Leia também

Newsletter semanal

O essencial da tecnologia, toda sexta no seu e-mail

Uma curadoria da redação com as notícias que importam para quem desenvolve, joga e trabalha com tecnologia. Sem spam.

Ao assinar, você concorda com a política de privacidade. Cancele quando quiser.