Idempotência dentro do backend além da API pública

O problema

Quando o assunto é idempotência, muita gente pensa só em:

• POST /payments
• retry do cliente
• Idempotency-Key

Só que o backend repete trabalho em vários outros lugares:

• job reenfileirado
• webhook entregue de novo
• consumer reiniciado
• backfill rodado mais de uma vez
• evento reprocessado depois de falha parcial

Se a proteção só existe na borda pública, a duplicação continua viva por dentro.

Modelo mental

A pergunta útil não é:

“essa operação é idempotente em teoria?”

A pergunta útil é:

“qual efeito não pode acontecer duas vezes?”

Porque repetir leitura quase nunca dói.

Repetir efeito colateral, sim.

Exemplos de efeito sensível:

• cobrar
• enviar crédito
• reservar recurso escasso
• registrar movimento financeiro
• disparar integração irreversível

Onde o problema aparece de verdade

Dentro do backend, a duplicação costuma entrar por:

• retry automático
• timeout com estado parcial
• reentrega de mensagem
• reprocessamento manual
• restart de worker

Tudo isso é normal.

O erro é tratar repetição como acidente raro.

Em sistema real, repetição é cenário esperado.

Exemplo simples

Imagine um consumer de order_paid.

Ele faz:

• marcar pedido como pago
• liberar comissão
• publicar evento de confirmação

Se esse consumer rodar duas vezes e não houver proteção, você pode:

• pagar comissão dobrada
• publicar confirmação duplicada

Idempotência aqui não é “luxo de API”.

É proteção de fluxo interno.

O que normalmente ajuda

Dependendo do caso, costuma ajudar:

• chave de negócio estável
• tabela de processamento
• upsert com restrição única
• checagem de estado antes de aplicar efeito
• outbox/inbox

Não existe uma única mecânica universal.

O importante é tornar “já vi isso” um caso tratável e explícito.

O erro comum

O erro comum é confundir duas coisas:

• evitar duplicar execução
• evitar duplicar efeito

Às vezes você não consegue impedir a execução repetida.

Mas ainda consegue impedir que o efeito crítico aconteça duas vezes.

Esse já é um desenho muito melhor do que depender de sorte.

Como um senior pensa

Quem decide melhor costuma perguntar:

• onde esse fluxo pode repetir legitimamente?
• qual efeito é irreversível ou caro?
• o que identifica a mesma intenção de negócio?
• como o sistema reage quando vê “isso já aconteceu”?

Essa leitura costuma ser melhor do que falar genericamente em deduplicação.

Ângulo de entrevista

Esse tema aparece em backend, jobs, webhooks, filas e incidentes de produção.

O entrevistador quer ver se você entende:

• que retry gera repetição legítima
• que exactly-once quase nunca é a garantia real
• como proteger efeito e não só execução

Resposta forte costuma soar assim:

“Eu trataria a possibilidade de repetição como normal e protegeria o efeito sensível com chave de negócio, estado já processado e semântica explícita para ‘já aplicado’. O objetivo não é impedir qualquer repetição de execução, e sim impedir duplicação do que realmente dói.”

Takeaway direto

Idempotência madura começa quando o time para de pensar só na API pública e começa a proteger os fluxos internos onde a duplicação realmente machuca.