# Idempotência em API: o que é e por que importa

> Idempotência em API é a propriedade que garante que múltiplas requisições idênticas produzem o mesmo resultado final, sem efeitos colaterais adicionais. Métodos HTTP como GET, PUT, DELETE e HEAD são idempotentes por padrão, enquanto POST não é. A implementação prática exige identificadores de requisição e verificação de estado no servidor para evitar duplicações.

*PosUp · Apps e Software · 02 de agosto de 2026 · Patrícia Lemos*

Idempotência garante que repetir uma requisição não altera o resultado final. Descubra como aplicar na prática e quais métodos HTTP seguem esse princípio.

Idempotência em APIs é a propriedade que garante que executar a mesma operação várias vezes produz o mesmo efeito final. Na prática, repetir uma requisição idempotente não gera duplicidade nem corrompe o estado do sistema. Métodos como GET, PUT, DELETE e HEAD são idempotentes; POST não é, por isso exige proteção adicional.

Se você já recebeu uma cobrança duplicada por um clique duplo no botão de compra, viu a ausência de idempotência em ação. O mesmo vale para uma transferência bancária processada duas vezes por causa de um timeout. Quando desenhamos APIs, a idempotência não é um enfeite: é uma decisão de negócio que evita retrabalho, retenção de clientes e prejuízo financeiro.

## O que significa idempotência em uma API?

Idempotência vem da matemática: uma operação é idempotente se aplicá-la duas vezes produz o mesmo resultado que aplicá-la uma vez. Em APIs, isso significa que uma requisição idempotente pode ser enviada múltiplas vezes sem efeitos colaterais adicionais.

Considere um GET em /usuarios/42. Repetir essa chamada 10 vezes retorna os mesmos dados do usuário, sem alterar nada no servidor. Esse é o caso mais simples. O desafio aparece em operações que alteram estado, como atualizar um recurso ou processar um pagamento.

A idempotência não significa que a resposta será idêntica a cada chamada. O que importa é o efeito final no sistema. Se a primeira chamada criou um recurso e a segunda retorna o mesmo recurso sem criar outro, a operação é idempotente.

## Quais métodos HTTP são idempotentes?

A especificação HTTP define quais métodos devem ser idempotentes. Essa distinção é essencial para clientes que fazem retry automático após falhas de rede.

- GET: idempotente por definição. Busca dados sem alterar estado.
- PUT: idempotente. Substitui o recurso por uma representação específica. Enviar o mesmo PUT duas vezes deixa o recurso no mesmo estado.
- DELETE: idempotente. O efeito final é o mesmo: o recurso deixa de existir. A segunda chamada pode retornar 404, mas o estado não muda.
- HEAD: idempotente, pois é um GET sem corpo.
- POST: não idempotente. Cada chamada pode criar um novo recurso ou disparar um efeito distinto.
- PATCH: não é idempotente por padrão, pois depende do conteúdo do patch. Um patch que incrementa um contador não é idempotente.

O MDN Web Docs reforça: um método HTTP é idempotente se uma requisição idêntica pode ser feita uma ou mais vezes com o mesmo efeito, deixando o servidor no mesmo estado. Essa definição é o norte para avaliar qualquer endpoint.

## Por que idempotência importa em APIs?

O valor da idempotência aparece quando algo dá errado. Timeouts, reinicializações de cliente e retries automáticos são comuns em sistemas distribuídos. Sem idempotência, cada retry pode criar um efeito colateral novo.

Um exemplo concreto: um serviço de pagamento recebe uma requisição de débito. O cliente não recebe a resposta a tempo e reenvia a mesma requisição. Se o endpoint não for idempotente, o cliente pode ser cobrado duas vezes. Com uma chave de idempotência, o servidor reconhece a requisição repetida e retorna o resultado original, sem novo débito.

Além de evitar duplicidade, a idempotência reduz a carga de debugging. Quando uma operação falha no meio do caminho, o time não precisa auditar logs para descobrir se o efeito foi aplicado ou não. A resposta da requisição repetida resolve a dúvida.

## Como implementar idempotência em uma API na prática?

A implementação mais comum é a chave de idempotência. O cliente gera um identificador único para a operação e o envia no cabeçalho da requisição. O servidor armazena esse identificador junto com a resposta da primeira execução.

Quando uma requisição chega com uma chave já processada, o servidor retorna a resposta armazenada, sem executar a operação novamente. Isso funciona bem para POST, que não é idempotente por padrão.

O fluxo típico:

- Cliente gera um UUID para a operação.
- Cliente envia o UUID no cabeçalho Idempotency-Key.
- Servidor verifica se a chave já existe.
- Se existe, retorna a resposta original.
- Se não existe, executa a operação, armazena a resposta e retorna.

O Stripe usa essa abordagem nos endpoints de pagamento. O PayPal também oferece chaves de idempotência para criar ordens. Em APIs internas, a mesma lógica se aplica a qualquer operação de escrita crítica.

Uma ressalva: a chave precisa ter expiração. Armazenar chaves para sempre infla o banco sem benefício. Em geral, 24 horas é um período razoável, mas depende do domínio. Uma operação de transferência pode precisar de 7 dias; um like em um post, de poucos minutos.

## Idempotência em mensageria e filas

APIs não são o único lugar onde a idempotência importa. Em sistemas de mensageria, consumidores podem receber a mesma mensagem mais de uma vez. Sem idempotência no processamento, isso gera efeitos duplicados.

Um consumidor de fila que processa um pedido duas vezes pode criar duas entregas. A solução é a mesma: um identificador único por mensagem, verificado no momento do processamento. Se o identificador já foi processado, o consumidor ignora a mensagem.

Em sistemas distribuídos, a idempotência é a base para a confiabilidade. Ela permite que componentes falhem e sejam reiniciados sem corromper o estado global.

## Quais os riscos de ignorar idempotência?

O risco mais visível é a duplicação de efeitos: cobranças, envios de e-mail, criação de registros. Menos visível, mas igualmente danoso, é a perda de confiança dos clientes da API. Uma integração que gera dados duplicados força o consumidor a implementar proteções próprias, o que aumenta a complexidade do lado de quem consome.

Outro risco é a inconsistência de dados. Uma operação não idempotente que falha no meio do caminho pode deixar o sistema em um estado parcial. Sem idempotência, é difícil saber se a operação foi aplicada ou não, e o retry pode agravar o problema.

Em APIs financeiras, a ausência de idempotência pode levar a violações regulatórias, além de prejuízo direto. A auditoria de transações duplicadas consome tempo e pode gerar multas.

## Idempotência é o mesmo que segurança?

Não. Idempotência não substitui autenticação, autorização ou criptografia. Ela trata de consistência de efeitos, não de acesso. Uma API pode ser perfeitamente idempotente e ainda assim vulnerável a ataques.

No entanto, a idempotência tem um papel indireto na segurança. Ela impede que um atacante que intercepta uma requisição legítima e a reenvia cause um efeito duplicado. Um replay de uma operação idempotente não gera dano adicional.

Mas não confunda: um atacante que reenvia uma requisição de transferência com uma chave nova ainda pode criar uma nova transferência. A proteção contra replay exige autenticação forte e validação de origem, além de idempotência.

## Como testar idempotência em uma API?

Testar idempotência é simples: envie a mesma requisição duas vezes e compare o efeito final. Para GET, basta verificar que o recurso não mudou. Para PUT, envie o mesmo payload duas vezes e confira que o estado é o mesmo. Para DELETE, a segunda chamada pode retornar 404, mas o recurso não deve ser recriado.

Para operações com chave de idempotência, envie a mesma chave com payloads diferentes. O servidor deve retornar a resposta original, ignorando o novo payload. Se o servidor processar o segundo payload, a implementação está falha.

Automatize esses testes em CI para evitar regressões. Um teste que envia a mesma requisição POST duas vezes e verifica que apenas um recurso foi criado já cobre o caso mais comum.

## Resumo

Idempotência em APIs garante que repetir uma operação não altera o resultado final. Métodos como GET, PUT e DELETE são idempotentes; POST não é. Para operações críticas, use chaves de idempotência e teste o comportamento de retry. Sem isso, cada retry é uma roleta-russa de efeitos colaterais.

## Perguntas frequentes

### O que é idempotência em uma API REST?

Idempotência em uma API REST é a propriedade que permite executar a mesma requisição várias vezes com o mesmo efeito final. O servidor não cria efeitos colaterais adicionais além do primeiro. GET, PUT, DELETE e HEAD são idempotentes por padrão; POST e PATCH não são.

### Qual a diferença entre idempotência e segurança em APIs?

Idempotência trata de consistência de efeitos quando uma operação é repetida. Segurança trata de autenticação, autorização e proteção de dados. Uma API pode ser idempotente e insegura ao mesmo tempo. A idempotência complementa a segurança ao impedir que retries ou replays causem danos, mas não substitui controles de acesso.

### Como implementar idempotência em um endpoint POST?

Use uma chave de idempotência. O cliente envia um identificador único no cabeçalho da requisição. O servidor armazena esse identificador junto com a resposta da primeira execução. Em requisições repetidas com a mesma chave, o servidor retorna a resposta armazenada sem executar a operação novamente.

### Quais métodos HTTP são idempotentes?

GET, PUT, DELETE e HEAD são idempotentes. OPTIONS também é considerado idempotente. POST e PATCH não são idempotentes por padrão, pois cada chamada pode produzir um efeito distinto. A idempotência de PATCH depende do conteúdo do patch.

### Por que um retry pode causar duplicidade em uma API?

Um retry reenvia a mesma requisição após uma falha de rede ou timeout. Se o endpoint não for idempotente, cada envio executa a operação do zero. Em um pagamento, isso gera duas cobranças. Com idempotência, o servidor reconhece o retry e retorna o resultado original, evitando o efeito duplicado.

### Idempotência garante que a resposta será a mesma?

Não. A idempotência garante que o efeito final no servidor será o mesmo. A resposta pode variar, como um status 200 na primeira chamada e 404 na segunda de um DELETE. O que importa é que o estado do sistema não muda após a primeira execução.

---

Fonte (canonical): https://posup.com.br/apps-e-software/idempotencia-em-api-o-que-e-e-por-que-importa/