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.

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.

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.

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