Use isto quando precisar ensinar um conceito abstrato de forma concreta — combine uma demo prática com um pequeno glossário para que um leitor leigo saia com uma intuição, não apenas com uma definição.
Este é um exemplar copiável. Transponha a seção #demo para uma lição real construída a partir de assets/lesson-template.html — mantenha os tokens de design e o padrão Simples→Técnico tal e qual.
Idempotente significa que uma ação é segura para repetir: fazê-la uma vez, ou fazê-la cinco vezes, leva você exatamente ao mesmo lugar. A primeira tentativa muda as coisas; toda repetição depois disso silenciosamente não muda nada.
Isso importa porque o mundo real perde mensagens. Uma requisição de pagamento expira, a rede falha, um usuário toca duas vezes em "Pagar". Se o seu sistema não for idempotente, cada repetição cobra o cartão de novo. Se for, o cliente paga uma única vez, não importa quantas vezes a requisição chegue.
Pense como… o botão de um elevador. Aperte uma vez e a cabine vem. Aperte mais nove vezes enquanto espera — o elevador ainda vem exatamente uma vez. Os apertos extras não chamam nove elevadores. Um endpoint idempotente é esse botão.
O cliente gera uma chave de idempotência única (um UUID) uma única vez para a operação lógica e a reenvia em cada repetição. O servidor registra a chave junto com o resultado da primeira execução bem-sucedida.
Em uma requisição repetida, o servidor reconhece a chave, pula completamente o efeito colateral e reproduz a resposta armazenada. A cobrança dispara exatamente uma vez, mesmo que a requisição HTTP chegue muitas vezes. Stripe, PayPal e a maioria das APIs de pagamento exigem um cabeçalho Idempotency-Key exatamente por esse motivo.
Note a diferença em relação à semântica do HTTP: GET, PUT e DELETE são idempotentes por definição; POST não é — então um POST de "criar cobrança" precisa de uma chave explícita para se tornar seguro de repetir.
Dois sistemas de checkout, o mesmo cartão, o mesmo pedido de $42,00. Martele o botão e veja o que cada um faz. Apenas um deles protege o cliente.
Cada requisição que chega inicia uma cobrança totalmente nova. Sem memória do que já aconteceu.
Toda repetição carrega a mesma chave de idempotência. A primeira cobra; as demais reproduzem esse resultado.
Os dois lados recebem a mesma requisição a cada vez. A diferença está inteiramente em como o servidor lida com uma repetição.
function charge(req) { // sem chave, sem memória — sempre executa o efeito colateral payment.capture(req.card, 4200); return { status: "charged" }; }
const seen = new Map(); function charge(req) { const key = req.headers["Idempotency-Key"]; if (seen.has(key)) return seen.get(key); // reproduz const result = payment.capture(req.card, 4200); seen.set(key, result); // lembra o resultado return result; }
O punhado de termos usados acima, em palavras simples.
Idempotency-Key no código do servidor com chave.payment.capture() é o efeito colateral que queremos disparar exatamente uma vez.