Idempotência em API é a capacidade de repetir uma operação sem produzir um novo efeito de negócio quando aquela mesma ação já foi processada. Em integrações de sistemas, esse comportamento evita pedidos em dobro, cobranças repetidas, baixas duplicadas de estoque e cadastros recriados depois de timeout, perda de conexão ou retry automático.
O objetivo não é impedir novas tentativas. É permitir que elas ocorram com segurança. Se o cliente enviou uma operação, mas não recebeu a resposta, ele precisa conseguir repetir a mesma intenção sem transformar uma incerteza técnica em uma duplicidade operacional.
Resumo
- Idempotência preserva o mesmo efeito pretendido quando uma operação equivalente é repetida.
- PUT, DELETE e os métodos HTTP seguros são idempotentes por definição.
- POST e PATCH podem receber proteção adicional implementada pela aplicação.
- A mesma chave de idempotência precisa representar a mesma operação lógica durante os retries.
- Concorrência, expiração, persistência e payload divergente precisam fazer parte do contrato.
- Idempotência torna retries seguros, mas não define quando uma nova tentativa deve ocorrer.
O que é idempotência em API?
Uma operação é idempotente quando uma ou várias execuções equivalentes produzem o mesmo efeito pretendido no servidor.
Isso não significa que absolutamente nada mude entre as chamadas.
Logs podem registrar cada tentativa, métricas podem aumentar e a resposta HTTP da segunda chamada pode ser diferente. O que precisa permanecer equivalente é o efeito solicitado pela operação.
Um DELETE, por exemplo, pode remover o recurso na primeira chamada e responder de forma diferente quando for repetido. Ainda assim, o estado pretendido permanece o mesmo: o recurso continua removido.
Quais métodos HTTP são idempotentes?
Segundo a RFC 9110, os seguintes métodos são idempotentes por sua semântica definida:
| Método | Seguro | Idempotente |
|---|---|---|
| GET | Sim | Sim |
| HEAD | Sim | Sim |
| OPTIONS | Sim | Sim |
| TRACE | Sim | Sim |
| PUT | Não | Sim |
| DELETE | Não | Sim |
| POST | Não | Não por definição |
| PATCH | Não | Não por definição |
É importante não confundir método idempotente com operação de negócio idempotente.
Uma API pode implementar um POST para criar uma cobrança e permitir que o cliente repita aquele POST com a mesma chave sem gerar uma segunda cobrança. Nesse caso, a garantia não vem da semântica padrão do POST, mas do contrato desenvolvido pela aplicação.
Da mesma forma, a RFC 5789 não define PATCH como idempotente por padrão, embora uma API possa projetar determinada operação PATCH dessa maneira.
Por que idempotência é importante em integrações?
O caso clássico ocorre quando o cliente não sabe se a primeira tentativa funcionou.
- o sistema A solicita ao sistema B a criação de um pedido;
- o sistema B cria o pedido;
- a conexão é interrompida antes de a resposta chegar;
- o sistema A interpreta a operação como não confirmada;
- o cliente faz retry.
Sem idempotência, o sistema B pode criar um segundo pedido.
Com uma chave capaz de identificar a mesma intenção de negócio, o servidor reconhece que aquela operação já foi executada e evita o segundo efeito.
Onde o risco de duplicidade é maior?
| Cenário | Possível efeito duplicado | Controle |
|---|---|---|
| Pedido | Duas ordens para a mesma compra | Chave da operação + identificador de negócio |
| Pagamento | Duas cobranças | Idempotency key + reconciliação |
| Estoque | Duas baixas | ID único do evento |
| Cadastro | Cliente ou produto duplicado | Restrição de unicidade |
| Webhook | Evento processado várias vezes | ID do evento + persistência |
| Faturamento | Documento emitido novamente | Identificador de negócio + controle transacional |
Como funciona uma chave de idempotência?
Em operações mutáveis, especialmente POST, uma abordagem comum é o cliente gerar um identificador único para aquela intenção.
Se precisar repetir a operação, o cliente envia a mesma chave.
- Primeira chamada: o servidor registra a chave e executa a operação.
- Retry após conclusão: reconhece a chave e evita executar novamente o efeito de negócio.
- Mesma chave com outro payload: deve ser rejeitada ou tratada explicitamente como uso inválido.
- Duas requisições simultâneas: somente uma execução deve conseguir avançar conforme a política da API.
- Chave expirada: o comportamento precisa estar documentado.
Gerar uma chave nova em cada retry elimina justamente o mecanismo que permitiria ao servidor reconhecer que se trata da mesma tentativa lógica.
Um exemplo real: idempotência na API DICT do Pix
A API DICT do Banco Central oferece um exemplo concreto e brasileiro.
Na operação de criação de vínculo, a documentação informa que a requisição possui um campo RequestId, definido como UUID versão 4 e único no contexto do participante.
Esse identificador funciona como chave de idempotência.
Se uma requisição for repetida de forma compatível, a operação pode retornar resultado equivalente sem criar novamente o vínculo.
Mas, se um RequestId já utilizado reaparecer com parâmetros diferentes, a API prevê o erro RequestIdAlreadyUsed.
Esse comportamento representa uma regra essencial para qualquer implementação: uma mesma chave não deve representar duas intenções diferentes.
Idempotency-Key é um header HTTP oficial?
Ainda não.
O grupo HTTPAPI da IETF trabalhou no Internet-Draft draft-ietf-httpapi-idempotency-key-header.
A revisão mais recente foi a 07, mas o documento expirou em 18 de abril de 2026 e não se tornou RFC.
Isso não impede APIs de utilizarem Idempotency-Key como convenção. Significa apenas que a semântica não pode ser presumida universalmente.
Cada API precisa documentar:
- formato da chave;
- escopo;
- tempo de retenção;
- resposta para reutilização incompatível;
- comportamento quando a primeira requisição ainda está sendo processada;
- se existe fingerprint do payload.
Como PayPal e Stripe tratam idempotência?
PayPal
O PayPal utiliza o header PayPal-Request-Id em operações suportadas para impedir que uma nova tentativa complete a mesma ação mais de uma vez.
A documentação atual recomenda o identificador em chamadas que criam ou modificam dados e informa que sua retenção pode chegar a 45 dias em determinados endpoints.
Se duas solicitações simultâneas utilizarem o mesmo identificador, o comportamento também é tratado explicitamente pela plataforma.
Stripe
A Stripe permite chaves de idempotência em requisições POST e pode remover registros depois de pelo menos 24 horas.
Quando uma chave é reutilizada antes da expiração, a plataforma compara os parâmetros da nova requisição aos da original e gera erro quando eles divergem.
Os dois exemplos mostram que idempotência não é apenas “guardar um UUID”. Ela exige uma política completa de armazenamento, comparação, concorrência e expiração.
Como tratar duas requisições simultâneas com a mesma chave?
Esse é um dos cenários mais importantes e frequentemente esquecidos.
Imagine duas instâncias recebendo a mesma chave praticamente ao mesmo tempo. Se ambas consultarem o banco antes que qualquer uma registre a operação, as duas podem concluir que aquela chave ainda não existe e avançar.
A proteção precisa ser atômica.
Entre as estratégias possíveis estão:
- restrição única no armazenamento;
- insert atômico;
- controle transacional;
- lock distribuído quando realmente necessário;
- estado intermediário como
PROCESSING.
Uma segunda chamada pode então receber o resultado existente, aguardar, obter um conflito específico ou ser orientada a tentar novamente conforme o contrato da API.
Quanto tempo uma chave de idempotência deve ser armazenada?
Não existe um prazo universal.
A janela precisa cobrir o período em que uma repetição da mesma operação ainda é plausível.
Considere:
- política de retry do cliente;
- filas e reprocessamentos;
- tempo máximo de indisponibilidade esperado;
- volume de chaves;
- custo de armazenamento;
- criticidade do efeito duplicado.
Depois que a chave expira, uma requisição antiga pode voltar a parecer nova. É por isso que idempotência técnica não deve ser a única camada de proteção para operações críticas.
Confira também estes conteúdos relacionados:
- Veja como requests, respostas, erros e retries se encaixam no fluxo completo de uma integração via API.
- Saiba quando parar de repetir uma operação e encaminhar mensagens problemáticas para análise e reprocessamento controlado.
- Descubra quais regras de idempotência, erros, limites e versionamento precisam aparecer no contrato de uma API.
Chave de idempotência substitui uma regra de negócio?
Não.
Pedido, invoice, cobrança ou transação podem possuir identificadores naturais que também precisam ser únicos.
A chave técnica normalmente protege uma janela específica de retries. Já uma restrição de negócio pode impedir duplicidade mesmo dias ou meses depois.
Um pedido pode, por exemplo, ter:
- uma chave de idempotência da tentativa;
- um número externo único do pedido;
- uma restrição de unicidade no banco;
- reconciliação posterior entre origem e destino.
Essas camadas protegem riscos diferentes.
Idempotência e retry são a mesma coisa?
Não. Eles são complementares.
Retry responde à pergunta “quando tentar novamente?”. Idempotência responde a “como repetir sem produzir outro efeito?”.
Uma política de retry também precisa definir:
- quais erros são transitórios;
- quantidade máxima de tentativas;
- timeout;
- backoff;
- jitter;
- circuit breaker;
- destino depois da última tentativa.
Em uma situação que relatei no LinkedIn, acompanhei uma integração entrar em loop por causa do comportamento de uma API de terceiro mesmo com autenticação bem implementada.
Para mim, esse tipo de caso reforça que idempotência precisa fazer parte de uma estratégia maior de resiliência. Evitar duplicidade não impede sobrecarga, loops, timeout ou propagação de falhas entre serviços.
Idempotência garante processamento exactly once?
É melhor evitar tratar idempotência como uma garantia mágica de exactly once em todo o sistema distribuído.
O objetivo prático é permitir que uma mesma intenção chegue mais de uma vez sem que os efeitos observáveis de negócio sejam executados indevidamente várias vezes.
A operação pode atravessar filas, bancos, sistemas externos e processos independentes. Cada fronteira pode exigir seus próprios controles de deduplicação, transação, reconciliação ou compensação.
Por isso, uma arquitetura robusta combina idempotência com unicidade de negócio, rastreabilidade e reconciliação.
Quais métricas acompanhar?
| Indicador | O que ajuda a identificar |
|---|---|
| Retries por operação | Instabilidade nas dependências |
| Chaves repetidas | Quantidade de requisições reconhecidas como retry |
| Payload divergente | Uso incorreto da mesma chave |
| Concorrência da mesma chave | Chamadas simultâneas para a mesma intenção |
| Duplicidades de negócio | Falhas que escaparam da proteção técnica |
| Latência | Custo adicional da camada de controle |
| Falhas definitivas | Operações que não foram recuperadas por retry |
| Reprocessamentos | Necessidade de intervenção posterior |
Como implementar idempotência em API?
- Mapeie o efeito de negócio: descubra quais operações não podem ser executadas duas vezes.
- Diferencie HTTP de negócio: não presuma que escolher PUT ou POST resolve sozinho o problema.
- Defina a chave: formato, escopo e responsável por gerá-la.
- Associe a chave à intenção: mesma chave não deve aceitar outro payload ou operação incompatível.
- Garanta atomicidade: duas requisições simultâneas não podem avançar independentemente.
- Persista o resultado: defina o que será recuperado em retries posteriores.
- Defina expiração: a janela deve ser coerente com retries e reprocessamentos reais.
- Adicione proteção de negócio: identificadores e restrições de unicidade continuam necessários.
- Projete retry separadamente: erros transitórios, backoff, jitter e limites precisam de política própria.
- Monitore: acompanhe duplicidades, conflitos, retries e falhas de reprocessamento.
Repetir sem duplicar torna a integração mais resiliente
Timeouts, quedas de rede e respostas perdidas são inevitáveis em sistemas distribuídos. O que pode ser projetado é a forma como a arquitetura reage a essas incertezas.
Idempotência permite que o cliente tente novamente sem transformar uma falha de comunicação em pedido, cobrança ou evento duplicado.
Mas a proteção precisa combinar semântica HTTP, chave, persistência, concorrência, expiração, regra de negócio, retry e observabilidade.
A SysMiddle trabalha no desenho e sustentação de integrações entre APIs, ERPs, sistemas legados e plataformas digitais com tratamento de erros, monitoramento e mecanismos de resiliência adequados ao fluxo.
Se sua operação precisa suportar retries e reprocessamentos sem aumentar o risco de duplicidade, fale com um especialista da SysMiddle.
Perguntas frequentes sobre idempotência em API
É a capacidade de repetir uma operação equivalente sem produzir um novo efeito de negócio quando aquela mesma intenção já foi processada.
Segundo a RFC 9110, PUT, DELETE e os métodos seguros GET, HEAD, OPTIONS e TRACE são idempotentes. POST e PATCH não possuem essa garantia por definição.
Sim. Embora POST não seja idempotente por definição do HTTP, a aplicação pode implementar chaves, persistência e regras que reconheçam retries da mesma operação e impeçam um segundo efeito.
Não como RFC. A IETF desenvolveu um Internet-Draft para o header, mas a revisão 07 expirou em abril de 2026. Cada API que utiliza a convenção deve documentar seu comportamento.
Não existe prazo universal. A retenção deve cobrir a janela real de retries e reprocessamentos. Plataformas diferentes adotam períodos próprios e precisam documentar esse comportamento.
Não. Idempotência define como repetir sem criar um novo efeito. A política de retry define quando repetir, quais erros são recuperáveis, quantas tentativas fazer e quais intervalos utilizar.
