Idempotência: como evitar efeitos colaterais em operações repetidas

O que é idempotência

Uma operação segura de repetir sem medo

Uma operação é idempotente quando executá-la múltiplas vezes produz o mesmo resultado que executá-la uma única vez. Em termos práticos: se o cliente envia a mesma requisição duas vezes, dez vezes ou cem vezes, o estado do sistema no servidor deve ser o mesmo que seria com uma única execução. O conceito vem da matemática — multiplicar qualquer número por 1 é idempotente, porque o resultado nunca muda — mas em sistemas distribuídos tem um significado prático crítico: é o mecanismo que torna retries, reconexões e reenvios seguros de fazer sem consequências inesperadas para o usuário ou para os dados.

Por que idempotência importa em produção

Redes falham, timeouts acontecem, mensagens são entregues mais de uma vez

Em ambiente local, as requisições chegam e são processadas exatamente uma vez. Em produção real, redes são instáveis, servidores reiniciam, clientes implementam retry automático e filas de mensagens garantem entrega "ao menos uma vez" — não exatamente uma vez. Quando um cliente faz uma requisição de pagamento e recebe timeout antes da confirmação, ele não sabe se o servidor processou ou não. O que ele faz? Tenta de novo. Se a operação não for idempotente, o usuário é cobrado duas vezes. Se for idempotente, a segunda tentativa retorna o mesmo resultado da primeira — sem cobrar de novo. Essa é a diferença que separa um sistema confiável de um sistema que cria problemas silenciosos sob pressão.

Idempotência em HTTP: o que cada método garante

GET, PUT e DELETE são idempotentes por definição — POST não é

O protocolo HTTP define explicitamente quais métodos são idempotentes. GET é idempotente: buscar o mesmo recurso cem vezes retorna sempre o mesmo dado sem alterar nada. PUT é idempotente: atualizar um recurso com os mesmos dados chega sempre ao mesmo estado final, independente de quantas vezes for executado. DELETE é idempotente: deletar um recurso que já foi deletado resulta no mesmo estado — o recurso não existe — mesmo que o segundo DELETE retorne 404. POST não é idempotente por padrão: cada chamada cria um novo recurso ou dispara uma nova operação, o que é exatamente o comportamento indesejado em cenários de retry.

Idempotency Key: tornando POST seguro de repetir

Uma chave única que identifica a intenção, não a requisição

Para operações POST que precisam ser seguras de repetir — como criar um pagamento, enviar um email ou processar um pedido — o padrão da indústria é a Idempotency Key: uma chave única gerada pelo cliente e enviada no cabeçalho da requisição (normalmente Idempotency-Key). O servidor armazena a chave e o resultado. Na primeira vez que recebe a chave, processa a operação e salva o resultado. Se receber a mesma chave novamente, retorna o resultado armazenado sem processar de novo. O cliente gera uma nova chave para cada nova intenção e reutiliza a mesma chave em retries da mesma operação. Stripe, Adyen, Mercado Pago e praticamente toda API de pagamentos séria implementa exatamente esse padrão.

Exemplo prático — sistema de pagamento

Timeout no checkout: cobrar uma ou duas vezes?

Um usuário finaliza uma compra. O frontend envia uma requisição POST para criar o pagamento e gera uma Idempotency Key única (por exemplo, um UUID vinculado ao carrinho). O servidor processa, cobra o cartão, cria o registro e retorna 200. Mas a resposta não chega ao frontend por instabilidade de rede. O frontend, sem confirmação, tenta de novo com a mesma chave. O servidor identifica a chave já processada, retorna o resultado original sem cobrar de novo — o usuário recebe a confirmação. Sem idempotência: dois registros de pagamento, dois débitos, uma confusão para resolver manualmente. Com idempotência: um débito, um registro, usuário satisfeito.

Exemplo prático — fila de notificações por email

A mesma mensagem entregue duas vezes na caixa de entrada

Um sistema de boas-vindas publica uma mensagem na fila assim que o usuário se cadastra. O worker consome a mensagem, envia o email, mas falha antes de confirmar o processamento para a fila (ack). A fila reentrega a mensagem para outro worker — é o comportamento padrão de "ao menos uma vez" de sistemas como SQS e RabbitMQ. Sem idempotência no worker: dois emails de boas-vindas. Com idempotência: o worker verifica se já existe um registro de email enviado para aquele userId antes de processar. Se já existe, descarta. O resultado é sempre o mesmo: um email entregue, independente de quantas vezes a mensagem foi consumida da fila.

Quando a idempotência é crítica

Operações financeiras, envio de comunicações e ações com efeito único

Idempotência é especialmente crítica em: processamento de pagamentos (cobrança duplicada é o erro mais caro e mais difícil de reverter), envio de emails e notificações (spam acidental destrói confiança do usuário), criação de pedidos em e-commerce (dois pedidos do mesmo carrinho causam logística duplicada e custo desnecessário), provisionamento de recursos em nuvem (criar dois servidores em vez de um por retry é custoso e complexo de reverter) e operações de auditoria que precisam acontecer exatamente uma vez por evento. Em qualquer sistema que implementa retry automático, circuit breaker ou entrega de mensagens "ao menos uma vez", idempotência nas operações é pré-requisito, não otimização opcional.

Quando não se aplica ou exige cuidado

Operações naturalmente incrementais precisam de tratamento diferente

Nem toda operação deve ser idempotente de forma ingênua. Incrementar um contador de visualizações, registrar entradas em logs de auditoria ou acumular métricas são operações em que cada execução deve produzir um efeito distinto — e torná-las idempotentes significaria perder dados. O cuidado aqui é separar a intenção do efeito: a operação de registrar "usuário X visualizou o produto Y" deve acontecer uma vez por visualização real, mas o sistema precisa garantir que um retry da mesma requisição não registre duas visualizações. A solução é idempotência no nível do evento — rastrear qual evento já foi processado — não no nível do contador.

Como implementar: as estratégias mais usadas

Chave única, verificação antes de processar, resposta em cache

As estratégias práticas de implementação são: (1) Idempotency Key com tabela de rastreamento — armazenar a chave, o status e o resultado em banco, verificar antes de processar; (2) Chave natural do domínio — usar um identificador que já existe no negócio (orderId, userId+date, transactionHash) como chave idempotente em vez de criar uma nova; (3) Operações condicionais — usar UPDATE ... WHERE status = 'pendente' em vez de INSERT para evitar duplicatas; (4) Deduplicated event store — armazenar o ID do evento consumido e checar antes de processar (padrão comum em workers de fila). Cada abordagem tem trade-offs de complexidade e performance, mas todas compartilham o princípio: identificar de forma inequívoca o que já foi feito antes de fazer de novo.

Resumo — idempotência é confiabilidade, não perfeccionismo

O conceito que separa sistemas que sobrevivem à realidade de sistemas que funcionam apenas na demo

Em um mundo ideal, cada requisição chega exatamente uma vez e é processada exatamente uma vez. Na produção real, redes falham, clientes reenviam, filas reentregam. Idempotência é o mecanismo que torna esses cenários inofensivos: a operação pode ser executada múltiplas vezes e o resultado é sempre o mesmo. Implementar idempotência não é uma otimização avançada — é o nível mínimo de confiabilidade exigido de qualquer sistema que lida com dados financeiros, comunicações ou ações com efeito no mundo real. Continue em: Fundamentos obrigatórios antes de produção.