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

> Idempotência em API é a propriedade que assegura que múltiplas requisições idênticas gerem o mesmo efeito que uma única requisição. Em APIs REST, métodos GET, PUT e DELETE são idempotentes, enquanto POST não é. A idempotência previne duplicação de pedidos, inconsistências em transações financeiras e problemas causados por falhas de rede.

*Blog Sem Juízo · Novidades · 24 de julho de 2026 · Igor Bastos*

Idempotência em API garante que uma requisição repetida produza o mesmo resultado que a primeira. Em APIs REST, métodos como GET, PUT e DELETE são idempotentes por definição, enquanto POST não é. Isso evita duplicação de pedidos, inconsistência em pagamentos e falhas de rede.

## O que é idempotência em API e por que isso importa?

Idempotência em API significa que uma requisição pode ser executada uma ou várias vezes com o mesmo efeito final. Se você enviar a mesma chamada duas vezes, o estado do servidor depois da segunda chamada será idêntico ao estado depois da primeira. Isso não quer dizer que a resposta será igual, o servidor pode retornar um código diferente na segunda vez, mas o efeito colateral sobre os dados é o mesmo.

Em APIs REST, a idempotência é um contrato entre cliente e servidor. Quando um método é declarado idempotente, o cliente sabe que pode repetir a requisição sem medo de criar duplicatas ou corromper o estado. Isso é essencial em cenários de rede instável, retentativas automáticas e sistemas distribuídos, onde uma mensagem pode chegar mais de uma vez.

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

### GET: sempre idempotente

GET é o método mais seguro. Ele apenas recupera dados e não altera o estado do servidor. Executar GET duas vezes seguidas retorna o mesmo recurso (a menos que outro método tenha modificado o recurso entre as chamadas). Por definição, GET é idempotente e também seguro (sem efeitos colaterais).

### PUT: idempotente por definição

PUT substitui completamente um recurso no URI especificado. Se você enviar PUT /usuarios/123 com o mesmo corpo duas vezes, o recurso será sobrescrito com os mesmos dados na primeira vez e a segunda chamada não terá efeito adicional. O servidor pode retornar 200 na primeira e 204 na segunda, mas o estado final é o mesmo.

### DELETE: idempotente na prática

DELETE remove um recurso. A primeira chamada deleta o recurso e retorna 200 ou 204. A segunda chamada encontra o recurso ausente e retorna 404. Embora as respostas difiram, o efeito colateral é o mesmo: o recurso não existe mais. Por isso, DELETE é considerado idempotente.

### PATCH: nem sempre idempotente

PATCH é o ponto de atenção. Ele aplica uma modificação parcial no recurso. Se a modificação for baseada em um delta (como adicionar um item a uma lista), aplicar o mesmo PATCH duas vezes pode gerar resultados diferentes, por exemplo, adicionar o mesmo item duas vezes. Para ser idempotente, um PATCH precisa usar uma operação que, quando repetida, produza o mesmo estado final. Na prática, muitos desenvolvedores tratam PATCH como não idempotente e usam PUT quando a idempotência é crítica.

### POST: não idempotente

POST é usado para criar recursos ou enviar dados para processamento. Cada chamada POST normalmente gera um novo recurso ou uma nova ação. Enviar duas requisições POST idênticas pode criar dois registros duplicados. Por isso, POST nunca é considerado idempotente. Para contornar isso, sistemas usam tokens de idempotência (um identificador único enviado no cabeçalho) que permitem ao servidor reconhecer e ignorar requisições repetidas.

## Por que a idempotência é importante em APIs?

A idempotência resolve dois problemas comuns em sistemas distribuídos: retentativas automáticas e consistência de dados.

Quando um cliente envia uma requisição e a conexão cai antes de receber a resposta, ele não sabe se o servidor processou ou não a chamada. Sem idempotência, o cliente teria que arriscar uma duplicação ou deixar a operação incompleta. Com métodos idempotentes, ele pode simplesmente repetir a requisição.

Em sistemas financeiros, como processamento de pagamentos, a idempotência é obrigatória. Um POST para criar uma cobrança não é idempotente por padrão, então plataformas como Stripe e PayPal exigem que o cliente envie um cabeçalho Idempotency-Key. Se a requisição for repetida com a mesma chave, o servidor reconhece e retorna a resposta original sem processar novamente.

## Como garantir idempotência em APIs REST?

A maneira mais comum é usar um token de idempotência: um UUID ou string única gerada pelo cliente e enviada em um cabeçalho HTTP (como Idempotency-Key). O servidor armazena esse token junto com a resposta da primeira requisição. Se uma segunda requisição chegar com o mesmo token, o servidor retorna a resposta armazenada sem executar a operação.

Outra abordagem é projetar os endpoints para serem naturalmente idempotentes. Por exemplo, em vez de um POST que sempre cria um novo registro, use PUT com um ID gerado pelo cliente. Se o registro já existir, o PUT substitui; se não existir, cria. Isso torna a operação idempotente.

Em APIs que usam filas de mensagens (mensageria), a idempotência é implementada no consumidor. Cada mensagem carrega um identificador único, e o consumidor verifica se já processou aquele ID antes de executar a ação.

## Idempotência x segurança: qual a diferença?

Segurança (safe) e idempotência são conceitos diferentes, embora relacionados. Um método seguro é aquele que não altera o estado do servidor, GET e HEAD são seguros. Um método idempotente pode alterar o estado, mas o efeito é o mesmo se executado uma ou várias vezes, PUT e DELETE alteram o estado, mas são idempotentes.

Nem todo método idempotente é seguro (PUT não é seguro), e nem todo método seguro é idempotente (todos os seguros são idempotentes, por definição). A confusão comum é achar que idempotente significa "não altera nada". Na verdade, significa "altera sempre para o mesmo estado final".

## Resumo prático

Idempotência em API é a garantia de que repetir uma requisição não causa efeitos colaterais diferentes da primeira execução. Métodos GET, PUT e DELETE são idempotentes por padrão. POST não é. Para operações não idempotentes, use tokens de idempotência ou projete endpoints que permitam repetição segura. Em sistemas financeiros e de mensageria, a idempotência não é opcional, é requisito.

## FAQ: perguntas frequentes sobre idempotência em API

### GET é idempotente?

Sim. GET apenas recupera dados e não altera o estado do servidor. Executar GET várias vezes com os mesmos parâmetros retorna o mesmo recurso (salvo alterações feitas por outros métodos entre as chamadas).

### DELETE é idempotente mesmo retornando 404 na segunda vez?

Sim. A idempotência se refere ao efeito colateral, não à resposta. Na primeira chamada, o recurso é removido. Na segunda, o recurso já não existe. O estado final é o mesmo: recurso ausente.

### Como garantir idempotência em um POST?

Use um cabeçalho Idempotency-Key com um UUID gerado pelo cliente. O servidor armazena a chave e a resposta. Se a mesma chave for reenviada, o servidor retorna a resposta original sem processar novamente.

### PATCH é idempotente?

Depende da implementação. PATCH que adiciona itens a uma lista não é idempotente. PATCH que define um valor absoluto (como {"status": "ativo"}) é idempotente. Na dúvida, trate PATCH como não idempotente.

### Qual a diferença entre idempotente e seguro?

Seguro significa que o método não altera o estado do servidor (GET, HEAD). Idempotente significa que o efeito é o mesmo após uma ou várias execuções (PUT, DELETE). Todo método seguro é idempotente, mas nem todo método idempotente é seguro.

### Por que idempotência importa em microsserviços?

Em microsserviços, falhas de rede e retentativas são comuns. Sem idempotência, uma mesma mensagem pode ser processada duas vezes, gerando duplicatas, cobranças em dobro ou inconsistências. A idempotência garante que o sistema permaneça consistente mesmo com falhas.

---

Fonte (canonical): https://blogsemjuizo.com.br/novidades/idempotencia-em-api-o-que-e-e-por-que-importa/