# Idempotencia Estado: O Que E e Como Garantir

> Idempotencia Estado é um princípio de sistemas distribuídos que assegura que múltiplas execuções de uma mesma operação, com os mesmos parâmetros, resultem em estado final idêntico ao de uma única execução. A garantia exige identificadores únicos de requisição, validação de versão ou timestamps, e armazenamento de resultados anteriores. Implementações comuns incluem APIs REST com métodos PUT e DELETE, além de transações com verificação de pré-condições.

*Blog Sem Juízo · Destaques · 31 de agosto de 2026 · Zeca Maranhão*

Idempotencia de estado garante que varias chamadas a uma operacao produzam o mesmo resultado final. Veja o conceito, exemplos e como implementar.

Idempotencia de estado e a propriedade de uma operacao em que aplicar varias vezes produz o mesmo efeito final. Em APIs e sistemas distribuidos, isso significa que chamar um endpoint uma ou varias vezes com os mesmos parametros nao altera o resultado alem da primeira execucao. Garantir isso exige chaves de idempotencia, metodos HTTP adequados e controle de versao.

## O que exatamente e idempotencia de estado?

Idempotencia de estado se refere a operacoes que, quando executadas multiplas vezes, deixam o sistema no mesmo estado final que a primeira execucao. O termo vem da matematica: uma funcao f e idempotente se f(f(x)) = f(x). No contexto de software, uma operacao idempotente pode ser repetida sem causar efeitos colaterais adicionais.

Considere um exemplo simples: definir o valor de uma variavel como 5. Executar essa operacao uma vez ou dez vezes resulta no mesmo valor final. Por outro lado, incrementar uma variavel de 1 para 2 nao e idempotente, pois cada chamada altera o estado.

Em APIs REST, o metodo GET e naturalmente idempotente: buscar um recurso varias vezes nao muda nada. O metodo PUT, que substitui um recurso, tambem e idempotente. Ja o POST, que cria um recurso, nao e idempotente por padrao, pois cada chamada pode criar um novo item.

## Por que idempotencia de estado importa em sistemas distribuidos?

Em sistemas distribuidos, falhas de rede, timeouts e retries sao inevitaveis. Um cliente pode enviar uma requisicao, nao receber a resposta a tempo e reenviar a mesma requisicao. Sem idempotencia, essa segunda chamada pode duplicar uma transacao, criar um registro repetido ou processar um pagamento duas vezes.

Um exemplo classico e um pagamento online. Se o cliente clica em "pagar" e a conexao cai, o sistema pode tentar novamente. Sem idempotencia, o valor seria cobrado duas vezes. Com idempotencia, a segunda tentativa reconhece que a primeira ja foi processada e retorna o mesmo resultado.

Outra situacao comum envolve filas de mensagens. Um consumidor pode processar uma mensagem, falhar ao confirmar o recebimento e recebe-la novamente. Se o processamento nao for idempotente, o efeito sera duplicado.

## Como garantir idempotencia de estado em APIs?

Garantir idempotencia de estado exige uma combinacao de design e implementacao. A primeira medida e usar os metodos HTTP corretamente. GET, PUT, DELETE e HEAD sao idempotentes por definicao. POST e PATCH nao sao, mas podem ser adaptados.

Para operacoes nao idempotentes, uma estrategia comum e o uso de chaves de idempotencia. O cliente gera um identificador unico (como um UUID) e o envia no cabecalho da requisicao. O servidor armazena esse identificador junto com o resultado da primeira execucao. Se a mesma chave chegar novamente, o servidor retorna o resultado armazenado, sem reprocessar.

Um exemplo pratico: um endpoint POST /api/pedidos pode aceitar um cabecalho Idempotency-Key. Na primeira chamada, o pedido e criado e a chave e registrada. Na segunda, o servidor verifica que a chave ja existe e retorna o pedido original, evitando duplicacao.

Outra abordagem e tornar a operacao naturalmente idempotente no nivel de dados. Por exemplo, em vez de incrementar um contador, pode-se definir um valor absoluto. Ou usar uma constraint de unicidade no banco de dados para impedir registros duplicados com base em um campo unico.

## Quais metodos HTTP sao idempotentes e quais nao sao?

Os metodos GET, HEAD, PUT, DELETE e OPTIONS sao considerados idempotentes. Isso significa que multiplas requisicoes identicas produzem o mesmo efeito no servidor, embora a resposta possa variar. O DELETE, por exemplo, pode retornar 200 na primeira chamada e 404 na segunda, mas o estado final (recurso removido) e o mesmo.

O metodo POST nao e idempotente por padrao, pois foi projetado para criar recursos. O PATCH tambem nao e, pois pode modificar parcialmente um recurso de forma nao deterministica. Para usar POST ou PATCH de forma idempotente, e necessario implementar mecanismos adicionais como chaves de idempotencia.

Um ponto de atencao: idempotencia nao significa que a resposta sera identica. Duas chamadas DELETE podem retornar codigos diferentes, mas o estado final do recurso e o mesmo. O que importa e o efeito no servidor, nao a resposta exata.

## Como implementar chaves de idempotencia de forma segura?

Implementar chaves de idempotencia exige cuidado com concorrencia e persistencia. O servidor deve armazenar a chave em um banco de dados ou cache distribuido com alta disponibilidade. A chave deve ter expiracao para evitar acumulo, mas longa o suficiente para cobrir retries.

Um desafio comum e a corrida entre duas requisicoes simultaneas com a mesma chave. Para resolver, use uma constraint de unicidade no banco ou um lock distribuido. A primeira requisicao insere a chave; a segunda tenta inserir e falha, entao retorna o resultado da primeira.

Tambem e importante incluir a chave na resposta, para que o cliente possa correlacionar. E recomendavel registrar o corpo da requisicao junto com a chave, para detectar conflitos se o cliente enviar dados diferentes com a mesma chave.

Um contraexemplo: se a chave for armazenada apenas em memoria, um restart do servidor apaga tudo. Isso quebra a garantia de idempotencia. Por isso, a persistencia em um armazenamento duravel e essencial em producao.

## Quais erros comuns acontecem ao tentar garantir idempotencia?

Um erro frequente e confundir idempotencia com seguranca. Idempotencia nao impede que uma operacao seja repetida; apenas garante que o efeito seja o mesmo. Outro erro e aplicar chaves de idempotencia apenas ao endpoint de criacao, esquecendo de atualizacoes e exclusoes.

Outro problema e nao considerar a expiracao da chave. Se a chave expirar antes do cliente concluir a operacao, uma nova chamada pode duplicar o efeito. O tempo de expiracao deve ser maior que o tempo maximo de retry do cliente.

Tambem ha o erro de retornar respostas diferentes para a mesma chave. Se a primeira chamada retorna 201 e a segunda retorna 200, o cliente pode nao saber se a operacao foi criada ou ja existia. O ideal e retornar o mesmo status e corpo na repeticao.

## Como testar idempotencia de estado?

Testar idempotencia envolve enviar a mesma requisicao varias vezes e verificar que o estado final permanece inalterado. Isso pode ser feito com testes de integracao que chamam o endpoint repetidamente com a mesma chave e comparam o estado do banco.

Um teste simples: crie um recurso com uma chave, depois envie a mesma requisicao mais duas vezes. O banco deve ter apenas um registro. Tambem teste com requisicoes concorrentes usando a mesma chave, para verificar que apenas uma executa.

Outra pratica e simular falhas de rede e retries. Um teste pode interromper a conexao apos o envio da requisicao e reenviar, verificando que o servidor nao processa duas vezes.

Ferramentas como Postman e scripts de teste podem automatizar esse fluxo. O importante e cobrir tanto o caminho feliz quanto os cenarios de falha e repeticao.

## Resumo

Idempotencia de estado e uma propriedade essencial para sistemas confiaveis. Ela garante que operacoes repetidas nao causem efeitos duplicados, protegendo contra falhas de rede e retries. Para garantir, use metodos HTTP idempotentes, chaves de idempotencia com persistencia duravel e constraints de unicidade no banco. Teste cenarios de repeticao e concorrencia para validar o comportamento.

## FAQ

### O que significa idempotencia em programacao?

Idempotencia em programacao significa que uma operacao pode ser executada varias vezes sem alterar o resultado alem da primeira execucao. Por exemplo, definir uma variavel como 5 e idempotente, mas incrementar de 1 para 2 nao e. O conceito e crucial em APIs e sistemas distribuidos.

### Qual a diferenca entre idempotencia e seguranca?

Seguranca se refere a operacoes que nao modificam o estado, como GET. Idempotencia se refere a operacoes que podem modificar o estado, mas de forma repetida produzem o mesmo efeito final. DELETE e idempotente, mas nao e seguro, pois remove um recurso.

### Como usar chave de idempotencia?

O cliente gera um identificador unico, como um UUID, e o envia no cabecalho da requisicao (ex: Idempotency-Key). O servidor armazena a chave e o resultado da primeira execucao. Em chamadas subsequentes com a mesma chave, o servidor retorna o resultado salvo.

### Post e idempotente?

Por padrao, POST nao e idempotente, pois foi projetado para criar recursos e cada chamada pode gerar um novo item. Para tornar um endpoint POST idempotente, implemente chaves de idempotencia ou constraints de unicidade no banco.

### O que acontece se a chave de idempotencia expirar?

Se a chave expirar antes do cliente concluir a operacao, uma nova chamada pode ser tratada como uma nova requisicao, causando duplicacao. Por isso, o tempo de expiracao deve ser maior que o tempo maximo de retry do cliente.

### Idempotencia garante que a resposta seja a mesma?

Nao. Idempotencia garante que o efeito no servidor seja o mesmo, mas a resposta pode variar. Por exemplo, um DELETE pode retornar 200 na primeira chamada e 404 na segunda, mas o recurso continua removido.

---

Fonte (canonical): https://blogsemjuizo.com.br/destaques/idempotencia-estado-o-que-e-e-como-garantir/