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, isso evita pedidos em dobro, cobranças repetidas, baixas duplicadas de estoque e cadastros recriados depois de timeout, falha de rede ou retry automático.
O ponto central não é impedir novas tentativas, mas torná-las seguras. Se o cliente não recebeu a resposta, ele precisa poder reenviar a operação sem transformar uma incerteza técnica em uma duplicidade operacional.
Resumo
- Idempotência preserva o mesmo efeito de negócio quando uma requisição equivalente é repetida.
- PUT, DELETE e os métodos HTTP seguros são idempotentes por definição; POST e PATCH exigem análise adicional.
- Uma chave de idempotência deve identificar a mesma operação lógica durante os retries.
- A mesma chave não deve ser reutilizada para payloads diferentes.
- Concorrência, expiração da chave, persistência do resultado e observabilidade precisam fazer parte do contrato.
- Idempotência e retry são complementares: uma não substitui a estratégia da outra.
Fatos rápidos
- Exemplo brasileiro em produção: a API DICT do Banco Central usa o campo
RequestId, um UUID v4, como chave de idempotência e rejeita seu reaproveitamento com parâmetros diferentes. - Idempotência também aparece na API Pix: o Manual de Padrões para Iniciação do Pix relaciona o
txidà garantia de idempotência e diferencia a criação por PUT da alternativa por POST. - Semântica HTTP: a RFC 9110 define como idempotentes PUT, DELETE e os métodos seguros; repetir a chamada pode gerar resposta diferente sem alterar essa propriedade.
O que é idempotência em API?
Uma operação é idempotente quando executar a mesma intenção uma vez ou várias vezes produz o mesmo efeito final esperado no servidor. Isso não significa que absolutamente nada possa acontecer novamente: logs podem registrar cada tentativa e a resposta HTTP da segunda chamada pode ser diferente da primeira.
Um DELETE, por exemplo, pode remover um recurso na primeira chamada e retornar uma resposta diferente quando repetido depois. Ainda assim, o efeito pretendido continua sendo o mesmo: o recurso permanece removido.
Também é importante separar idempotência do método HTTP de idempotência da operação de negócio. Uma API pode desenhar um POST de pagamento para que retries com a mesma chave não gerem uma segunda cobrança. Nesse caso, a segurança da repetição vem do contrato implementado pela aplicação.
Códigos HTTP também não resolvem a duplicidade sozinhos. O manual da API FNRH, por exemplo, documenta respostas como 409 Conflict. O significado do conflito, porém, precisa ser definido no contrato de cada API; o código 409, isoladamente, não torna uma operação idempotente.
Como aplicar idempotência em API com foco em resultado
O primeiro passo é mapear operações em que uma repetição indevida produz impacto financeiro ou operacional. Pedido, faturamento, cobrança, separação, atualização de saldo, cadastro e processamento de webhooks normalmente merecem atenção prioritária.
A documentação da MDN sobre idempotência ajuda a visualizar a distinção entre os métodos HTTP, enquanto a RFC 9110 fornece a definição normativa. GET e HEAD são seguros e idempotentes; PUT e DELETE também são idempotentes por semântica. POST não possui essa garantia por padrão.
PATCH exige um cuidado adicional. A RFC 5789 não o define como idempotente por padrão, embora uma implementação possa desenhá-lo dessa maneira. Por isso, a escolha do verbo não elimina a necessidade de entender o efeito concreto da operação.
Onde o risco de duplicidade é maior
| Cenário | Risco da repetição | Controle de idempotência | Complemento recomendado |
|---|---|---|---|
| Pedido industrial | Duas ordens para a mesma compra | Chave única por operação | Restrição de unicidade e rastreabilidade |
| Pagamento ou faturamento | Cobrança ou documento repetido | Idempotency key ou identificador de negócio | Reconciliação e registro do resultado |
| Estoque | Baixa duplicada | Identificador único do evento | Controle transacional |
| Cadastro | Registro duplicado | Regra de unicidade e chave da operação | Validação de dados mestres |
| Webhook | Mesmo evento processado várias vezes | ID único do evento | Persistência dos eventos já consumidos |
Como usar uma chave de idempotência
Em operações como POST, uma abordagem comum é o cliente gerar uma chave única e reenviar a mesma chave enquanto estiver tentando concluir a mesma ação lógica. Gerar uma chave nova a cada retry elimina justamente a capacidade de o servidor reconhecer a repetição.
- primeira tentativa: o servidor registra a chave e inicia o processamento;
- retry depois da conclusão: a API recupera o resultado já associado àquela operação em vez de executá-la novamente;
- mesma chave com payload diferente: o contrato deve rejeitar a reutilização, porque a chave não representa mais a mesma intenção;
- requisições concorrentes: o servidor precisa impedir que duas execuções com a mesma chave avancem simultaneamente;
- expiração: a política de retenção da chave deve cobrir a janela real de retries e ser documentada.
A IETF trabalhou em uma proposta de padronização para o cabeçalho Idempotency-Key. Uma versão do rascunho já descrevia a chave para tornar POST e PATCH mais tolerantes a falhas. A revisão mais recente chegou à versão 07, mas expirou em abril de 2026 e não se tornou RFC. Portanto, o cabeçalho deve ser tratado como convenção definida pelo contrato da API, e não como um campo HTTP padronizado de forma definitiva.
A proposta mais recente também descreve boas práticas úteis para desenho interno: não reutilizar a mesma chave com payload diferente, definir validade, opcionalmente calcular um fingerprint do request e tratar de forma específica uma segunda solicitação enquanto a primeira ainda está em processamento.
Implementações reais seguem políticas próprias. O PayPal, por exemplo, usa o cabeçalho PayPal-Request-Id em chamadas suportadas e documenta retenção de até 45 dias em determinados endpoints. Isso mostra por que cliente e servidor precisam concordar sobre formato, escopo e validade da chave.
Idempotência e retry precisam ser desenhados juntos
Idempotência não define quando tentar novamente. Uma estratégia de retry também precisa considerar quais erros são transitórios, limite de tentativas, backoff, jitter, timeout e eventual fila de reprocessamento. Sem isso, centenas de clientes podem repetir chamadas ao mesmo tempo justamente quando o sistema de destino está tentando se recuperar.
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 conviver com rate limiting, timeouts, circuit breakers e observabilidade: impedir duplicidade resolve uma parte do problema, não toda a resiliência do fluxo.
Chave de idempotência não substitui regra de negócio
Uma chave técnica protege a repetição de uma mesma tentativa, mas pode ser insuficiente quando o próprio negócio possui um identificador natural. Pedido, invoice, transação ou evento podem exigir restrições de unicidade independentes da chave de retry.
Essa segunda camada é especialmente importante depois que a chave de idempotência expira. Se uma requisição antiga reaparecer fora da janela de retenção, uma regra de negócio ainda pode impedir que uma obrigação já processada seja criada novamente.
Métricas que a gestão deve acompanhar
Não basta implementar e presumir que o problema desapareceu. Monitore taxa de duplicidade, retries por operação, conflitos de chave, latência, falhas definitivas, reprocessamentos manuais e percentual de sucesso.
Esses indicadores mostram se a integração apenas responde ou se realmente tolera falhas sem gerar efeitos extras. Em ambientes maiores, isso deve fazer parte de uma estratégia de integração de sistemas que combine arquitetura, observabilidade e governança.
Etapas objetivas
- Mapeie operações críticas e o efeito de negócio de uma repetição.
- Separe a idempotência definida pelo método HTTP da idempotência implementada pela aplicação.
- Defina chave, escopo, fingerprint quando necessário e política de expiração.
- Garanta persistência e exclusão mútua ou operação atômica para a mesma chave.
- Desenhe retries, timeouts e recuperação de falhas de forma complementar.
- Documente respostas para repetição concluída, concorrência e payload divergente.
- Monitore indicadores e revise o comportamento em produção.
Confira também estes conteúdos relacionados:
- Saiba o que é integração via API e como funciona na prática
- O que é REST API e como ela se conecta às integrações empresariais
- Simplificar integrações complexas reduz falhas e acelera a operação
Repetir sem duplicar melhora a operação
Idempotência em API transforma retries inevitáveis em comportamento previsível. Quando chave, persistência, concorrência, regras de negócio e observabilidade são definidas em conjunto, uma falha de comunicação deixa de significar pedido repetido, cobrança duplicada ou inconsistência entre sistemas.
Em ambientes com alto volume, esse cuidado precisa fazer parte do contrato da integração desde o desenho. Se a sua operação precisa escalar sem aumentar retrabalho e risco de duplicidade, entre em contato com a SysMiddle.
Perguntas frequentes (FAQ)
É a propriedade que permite repetir uma operação equivalente sem produzir um novo efeito de negócio quando ela já foi processada. É especialmente útil em timeouts, falhas de rede e retries automáticos.
Sim. POST não é idempotente por definição do HTTP, mas a aplicação pode adicionar uma chave de idempotência, persistência do resultado e regras que reconheçam retries da mesma operação sem criar um segundo efeito.
Segundo a RFC 9110, os métodos seguros e também PUT e DELETE são idempotentes. PATCH não é idempotente por padrão, e POST precisa de semântica adicional quando a operação deve tolerar repetição.
Ainda não como RFC. A IETF trabalhou em um Internet-Draft para o cabeçalho Idempotency-Key, mas a revisão 07 expirou em abril de 2026. APIs que adotam a convenção precisam documentar sua própria semântica e política.
Não. Idempotência torna determinadas repetições seguras; retry decide quando e quantas vezes repetir. Uma estratégia robusta combina idempotência com timeout, backoff, jitter, limites de tentativa, observabilidade e tratamento de falhas.
