Idempotência: o conceito que todo dev sênior precisa dominar
Como evitar que o mesmo pagamento seja processado duas vezes: chave de idempotência, filas, APIs externas e os trade-offs.
Idempotência é um conceito que eu usei em todas as empresas em que trabalhei. E é, de longe, um dos que mais caem em entrevista de back-end.
Neste artigo eu quero te explicar idempotência do jeito mais prático possível: o que é, quando você não precisa dela, como implementar, quais falhas cada peça cobre e quanto isso custa. No final, deixo a resposta curta que eu daria se alguém me perguntasse sobre isso numa entrevista.
1. O que é idempotência#
Imagina um sistema de pagamentos. De um lado, um cliente. Do outro, um servidor. O cliente faz uma chamada HTTP pedindo pra adicionar R$ 20 numa conta, e o servidor grava isso no banco.
Só que o cliente, como todo sistema bem feito, é resiliente: se alguma coisa der errado, ele faz retry, ou seja, manda a mesma chamada de novo. Digamos que ele tentou quatro vezes: deu erro em três e só teve sucesso na quarta.
O que acontece no servidor? Adiciona R$ 20, depois mais R$ 20, mais R$ 20 e mais R$ 20. A intenção do usuário era uma transação de R$ 20, e o resultado foi um saldo de R$ 80.
Quando um sistema se comporta assim, ele é não idempotente: a mesma intenção foi processada várias vezes e o resultado ficou inconsistente.
Num sistema idempotente, o cenário é o mesmo (o cliente pode falhar e repetir a chamada quatro vezes), mas existe uma estrutura entre cliente e servidor que garante que o resultado final seja só R$ 20.
2. O pior caso: o timeout#
O cliente manda "adicionar R$ 20" e a resposta nunca volta. Deu timeout. O que pode ter acontecido? Três coisas:
A requisição saiu do cliente e nunca chegou no servidor.
Ela chegou e deu erro dentro do servidor.
Ela chegou, foi processada com sucesso, mas a resposta se perdeu na volta.
O terceiro caso é o pior. Os R$ 20 já foram adicionados, mas o cliente não sabe disso. Então ele manda de novo, o servidor processa de novo, e no fim a conta recebeu R$ 40.
3. Antes de implementar: você precisa mesmo?#
Antes de sair implementando, a primeira pergunta é se a sua operação já não é naturalmente idempotente. Dá pra ver isso de dois jeitos: pela regra de negócio e pelo método HTTP.
Pela regra de negócio#
Definir o saldo como R$ 100: idempotente. Não importa quantas vezes você mande, o saldo final é R$ 100.
Somar R$ 10 ao saldo: não é. Cada execução soma mais 10.
Apagar uma chave Pix: idempotente. O estado final é o mesmo (a chave não existe), mesmo que a resposta mude da primeira para a segunda vez.
Registrar uma chave Pix: idempotente com uma condição: o banco de destino precisa ter uma restrição de unicidade nessa chave. Se tentar registrar de novo, dá erro de unicidade e nada duplica.
Enviar um Pix de R$ 50: não é. Mandou duas vezes, saíram R$ 100.
A regra que eu uso: sempre que a operação é relativa a um estado anterior (somar, incrementar, enviar mais um), ela não é idempotente por natureza.
Pelo método HTTP#
A própria especificação do HTTP (RFC 9110) define quais métodos são idempotentes:
GET: busca dados. Idempotente.POST: cria ou executa alguma coisa. Não dá pra garantir. Pode ser, mas não é por definição.PUT: substitui o recurso inteiro (ou cria, se não existir). Idempotente: mandar o mesmo PUT de novo deixa o recurso igual.PATCH: atualiza parte do recurso. Depende da alteração: "mudar o nome pra Yudi" é idempotente, "somar 10 reais" não é.DELETE: apaga. Idempotente: apagando uma ou dez vezes, o recurso não existe no fim.
Um detalhe importante: isso é o padrão. Na prática, cada empresa segue de um jeito, e muita API não respeita 100% a definição. Então se você já teve dificuldade de entender a diferença entre esses métodos olhando os sistemas onde trabalhou, é normal.
Um caso real em que a resposta foi "não precisa"#
Numa das empresas em que trabalhei, quando uma conta era encerrada, a gente precisava apagar as chaves Pix dessa conta no Banco Central e também no nosso banco interno. Pra isso existia toda uma estrutura assíncrona, com um job de encerramento, vários estados numa máquina de estados e um job de reconciliação comparando a fonte da verdade com o nosso banco.
Só que olha a operação: apagar. E apagar já é naturalmente idempotente. Toda aquela estrutura era desnecessária.
A gente removeu. O sistema ficou muito mais simples de entender e, de quebra, os casos de inconsistência ficaram bem menos comuns, porque tinha muito menos coisa pra dar errado.
4. Implementando: a chave de idempotência#
Agora sim, quando a operação não é naturalmente idempotente (como "adicionar R$ 20"), a peça central é a idempotency key: uma chave única que identifica aquela intenção de transação.
O cliente gera a chave (por exemplo,
ID10) e salva no próprio banco antes de enviar.Ele manda o payload junto com a chave pro servidor.
O servidor também salva a chave no banco dele.
Se chegar de novo uma requisição com
ID10, o servidor percebe que já processou essa intenção e não adiciona os R$ 20 de novo. Só responde: "já fiz".
Repara que a chave resolve a ambiguidade: duas chamadas de R$ 20 podem ser legítimas (o usuário quis mesmo fazer duas transferências) ou um retry. Com chaves diferentes, são duas transações. Com a mesma chave, é a mesma.
Por que o cliente salva a chave no banco?#
Ele poderia só gerar a chave em memória e mandar. Mas se o processo do cliente morrer entre uma tentativa e outra, a chave some junto. No próximo retry ele gera uma chave nova, e o servidor vai achar que é outra transação. Salvar no banco antes de enviar é a garantia de que todo retry usa a mesma chave.
Quem cria a chave?#
A chave tem que nascer no momento em que a intenção da operação é criada, no primeiro sistema que registra aquela transação. A partir daí, ela trafega por todos os serviços do fluxo, e todos sabem que é tudo uma operação só.
Bônus: por isso a idempotency key também é ótima pra tracing de logs. Você consegue acompanhar uma mesma intenção de negócio passando por vários sistemas.
5. O que o servidor guarda (e por quê)#
Quanto mais complexidade você coloca, mais pontos de falha aparecem. O servidor também pode morrer no meio do caminho, e é por isso que ele guarda a chave no banco: quando voltar, ela está lá. Mas não é só a chave. A tabela de idempotência normalmente guarda:
Idempotency key (única): identifica a intenção.
Hash do request: detecta quando alguém manda a mesma chave com um corpo diferente. Isso indica bug, inconsistência ou até tentativa de fraude, e a requisição deve dar erro.
Status (processando ou concluído): diz o que fazer com um retry que chega no meio do caminho.
Response body: a resposta original, pra devolver igualzinha no retry.
Time to live (TTL): quanto tempo a chave fica guardada.
O retry chegou: o que responder?#
Ainda está processando: normalmente responde
409 Conflict.Já concluiu: responde como se fosse a primeira chamada, com o mesmo status (por exemplo,
201) e o mesmo response body.
Por que devolver o body original? Pensa num app fazendo uma transferência. Se ele precisou fazer um retry, ele quer receber exatamente a resposta que mostraria a tela de "transferência feita com sucesso". Um "já fiz" seco não serve.
Cuidado com o TTL#
A chave não precisa ficar guardada pra sempre. Pode durar, sei lá, um dia. Mas o TTL tem que estar em sintonia com quem faz o retry: se o cliente pode tentar de novo daqui a dois dias e a chave só vive um, o retry chega num servidor que já esqueceu da chave, e a duplicidade volta. Quando for integrar com um sistema, descubra quanto tempo a chave de idempotência dele dura.
6. Duas requisições no mesmo milissegundo#
E se duas requisições com a mesma chave chegarem ao mesmo tempo? Pode ser processamento paralelo, uma chamada que atrasou na rede... As duas perguntam pro banco "o ID10 já existe?", as duas ouvem "não" e as duas começam a processar.
Pode acontecer? Claro que pode. O que salva aqui é a própria estrutura: a idempotency key é uma chave única no banco. Quando o servidor tentar inserir a mesma chave pela segunda vez, o banco dá erro de unicidade. Só uma das duas consegue gravar, e só ela processa.
7. E se em vez do cliente fosse uma fila?#
Funciona do mesmo jeito, com a mesma tabela de idempotência. A diferença é que, em vez de responder sucesso pro cliente, você dá o ack (acknowledgement) pra fila, e só depois que todo o processamento terminou.
E em fila isso é ainda mais importante. Se você ler a documentação do RabbitMQ, do Kafka ou do SQS, vai encontrar a expressão at-least-once: a mensagem vai ser entregue pelo menos uma vez. Ou seja, ela pode chegar de novo, e garantir que isso não cause problema é responsabilidade sua.
Eles não fazem isso por maldade. Só quem sabe se a mensagem foi processada com sucesso é o seu sistema. Então a fila continua reenviando até você confirmar com o ack. Se você não confirmar, ela manda de novo, sem medo.
8. E se tiver uma API externa no caminho?#
Agora o seu servidor também é cliente de alguém: ele chama um sistema de pagamentos externo, que é a fonte da verdade (pode ser o Banco Central, por exemplo).
Mais uma peça, mais um ponto de falha. O servidor salva a chave, chama a API externa e, antes de marcar o status como concluído, morre. O registro fica como "processando". Quando alguém retomar esse registro, vai chamar a API externa de novo, e a transação pode duplicar lá do outro lado.
A partir daí, tem três caminhos:
A API externa aceita idempotency key: ótimo. Você manda a mesma chave nas duas chamadas e ela não duplica. É por isso que a chave tem que nascer no início da intenção e seguir até o fim do fluxo: se você mandasse uma chave nova pro sistema externo, não adiantaria nada.
Ela não aceita: dá pra consultar antes (um GET pra ver se o registro já existe) e só criar se não existir. É mais complexo, mas evita inconsistência.
Nada disso funciona: sobra a reconciliação. Um job que roda, por exemplo, todo dia às 3 da manhã, compara o que está na fonte da verdade (transações e saldo) com o seu banco interno e corrige as diferenças. O sistema externo é a fonte da verdade; o seu banco está ali pra apresentar os dados mais rápido.
Eu já tive casos assim. A reconciliação é a última linha de defesa contra inconsistência.
9. Modo Sênior: quanto custa tudo isso?#
Numa entrevista pra vaga sênior, saber implementar não basta. Você precisa falar dos trade-offs. No geral, o custo é sempre complexidade e uso de recursos, mas vale responder de forma específica:
Armazenamento: uma tabela (ou banco) pra chave, o hash, a resposta... no servidor e no cliente.
Limpeza: se o TTL é de um dia, alguma coisa precisa apagar essas chaves. Mais um job, mais complexidade.
Latência: cada requisição ganha passos a mais de leitura e escrita no banco.
"Então eu coloco a tabela de idempotência no Redis"#
Cuidado. Normalmente isso não é uma boa ideia, porque a chave precisa estar no mesmo banco do efeito. Você precisa gravar a chave e executar o +R$ 20 na mesma transação, senão perde a atomicidade: uma das duas coisas pode acontecer sem a outra.
O Redis faz sentido quando não existe efeito no seu banco interno pra proteger. Por exemplo, se o seu serviço só repassa uma mensagem pro sistema de pagamentos e não grava nada localmente.
10. A resposta de 30 segundos pra entrevista#
"Como você garantiria que um sistema de pagamentos não processe o mesmo pagamento duas vezes?"
Eu responderia assim:
Eu usaria idempotência. Partindo da premissa de que existe retry, o cliente gera uma idempotency key no início da intenção da transação e salva no banco antes de enviar. O servidor salva essa chave como única, junto com o hash do request e o response body. Se o cliente fizer retry, o servidor devolve a mesma resposta; se ainda estiver processando, responde 409 Conflict. Se tiver um sistema externo, eu passo a mesma chave pra ele. E se mesmo assim houver duplicidade do lado de lá, um job de reconciliação resolve no final.
Você não precisa decorar tudo isso#
É bastante coisa, mas a ideia não é saber de cor. No dia a dia você vai consultar: "como funciona mesmo um Transactional Outbox?", "posso salvar isso num Redis ou tem que ser no SQL?". O importante é ter o raciocínio. Com ele, até numa entrevista você consegue ir conversando com o entrevistador e chegar na solução.
E esse assunto cai em qualquer tipo de entrevista: system design, behavioral (quando você conta decisões de arquitetura que tomou) e até em exercício de código.
Se preferir ver tudo isso sendo desenhado, o vídeo completo está aqui no topo do artigo.
