Introdução: um clique, dois pedidos e um túnel onde as respostas se perdem

Imagine uma integração que funciona há anos. Seu serviço envia pedidos para um sistema externo, o fluxo passa por um pool de proxies móveis para distribuir as requisições por regiões e não esbarrar nos limites de um único endereço. Tudo estável. E de repente a contabilidade traz um relatório: no mês, o parceiro registrou quarenta e sete pedidos gêmeos. Produtos iguais, valores iguais, diferença de três a quatro segundos na data de criação. Ninguém mudou nada. O que aconteceu?

Aconteceu o mais comum: a conexão via proxy caiu no caminho de volta. O servidor recebeu a requisição, criou o pedido, enviou a resposta, mas a resposta não chegou ao cliente. O cliente concluiu honestamente que a requisição falhou e a repetiu. A segunda requisição também foi executada. É assim que nasce uma duplicata, e nenhuma política de retentativa por si só protege contra isso.

Aqui é importante traçar uma fronteira desde já. Sobre como repetir requisições corretamente após um erro 429, quanto esperar entre tentativas e como construir um backoff exponencial, escrevemos em outro artigo: esse é o tema da política de retentativas. Hoje a conversa é outra. Falamos sobre o contrato entre cliente e servidor que torna a repetição segura ou perigosa, independentemente de como você a executa. Esse contrato se chama idempotência, e sua principal ferramenta é a chave de idempotência.

Por que o tema é especialmente crítico justamente ao trabalhar com proxies? Porque o proxy adiciona mais um trecho à cadeia onde a resposta pode se perder. Proxies móveis, além disso, mudam o IP externo durante a rotação, e o servidor pode muito bem ver a segunda requisição vindo de outro endereço. Se sua proteção contra duplicatas depende de sessão, IP ou janela de tempo, ela desmorona. Se depende de uma chave de idempotência, não importa de onde veio a repetição.

Neste guia você vai aprender como a idempotência funciona no nível do protocolo e da lógica de negócio, como gerar e armazenar chaves, como projetar um armazenamento no servidor que aguenta retentativas concorrentes, o que fazer quando uma API externa não suporta chaves e em quais erros até equipes experientes tropeçam. Vamos analisar casos com números, montar checklists e responder às perguntas incômodas. O material é voltado para desenvolvedores de integrações, arquitetos e líderes técnicos que trabalham com pedidos, pagamentos e qualquer operação em que "duas vezes" significa "ruim".

Fundamentos: o que é idempotência e por que repetir uma requisição é perigoso

Definição em palavras simples

Uma operação é chamada de idempotente se executá-la várias vezes produz o mesmo resultado que executá-la uma única vez. Apertar o botão do elevador dez vezes é idempotente: o elevador virá uma vez. Adicionar mais uma unidade de um produto ao carrinho não é idempotente: cada clique altera o estado. Transferir dinheiro definitivamente não é idempotente, a menos que o sistema tenha sido projetado especificamente para que repetir a transferência com o mesmo identificador não faça nada.

No HTTP existem métodos que, por especificação, são considerados idempotentes: GET, PUT, DELETE, HEAD. Existe o método POST, que por padrão não é considerado idempotente. É justamente o POST que costuma ser usado para criar pedidos, pagamentos, enviar mensagens. Ou seja, a operação mais arriscada vive no método menos idempotente. Coincidência? Mais uma regularidade histórica com a qual precisamos lidar.

Três desfechos possíveis de qualquer requisição

Quando o cliente envia uma requisição e não recebe resposta, ele fica em estado de incerteza. Existem exatamente três cenários possíveis:

  • A requisição não chegou ao servidor. Repetir é seguro: nada aconteceu.
  • A requisição chegou, o servidor executou a operação, a resposta se perdeu. Repetir é perigoso: a operação será executada uma segunda vez.
  • A requisição chegou, o servidor começou a execução e ainda não terminou. Repetir é duplamente perigoso: duas operações serão executadas em paralelo.

O problema central é que o cliente não consegue distinguir esses cenários. Um timeout parece igual nos três casos. Uma conexão interrompida também. Daí decorre um princípio fundamental dos sistemas distribuídos: a entrega confiável só é possível como "pelo menos uma vez" (at-least-once). A garantia de "exatamente uma vez" (exactly-once) não pode ser obtida no nível de transporte; ela só pode ser emulada no nível da aplicação, tornando as repetições inofensivas. A idempotência é justamente essa forma de emulação.

Como o proxy alonga a cadeia de incerteza

Sem proxy, entre cliente e servidor há um único trecho de rede. Com proxy, são dois: cliente — proxy e proxy — servidor. A resposta pode se perder em qualquer um deles. E se ela se perder no primeiro trecho, o proxy já recebeu a resposta, o servidor já concluiu a operação e o cliente nunca ficará sabendo.

Proxies móveis adicionam particularidades. Eles têm rotação de IP por agendamento ou sob demanda, troca entre estações base e oscilações naturais de qualidade do canal de rádio. Cada um desses eventos pode romper a conexão TCP em um momento arbitrário. E na maioria das vezes a ruptura não acontece durante o envio do corpo da requisição (que é pequeno e voa rápido), mas durante a espera pela resposta, quando a conexão apenas fica aberta. É exatamente nesse momento que o servidor processa seu pedido. É exatamente nesse momento que a ruptura oferece a maior chance de duplicata.

O que é uma chave de idempotência

Chave de idempotência (Idempotency-Key) é um identificador único de uma operação de negócio, que o cliente gera uma vez e envia em cada tentativa de executar essa operação. O servidor memoriza a chave e o resultado. Em uma nova requisição com a mesma chave, o servidor não executa a operação de novo, mas retorna o resultado armazenado. O cliente pode repetir quantas vezes quiser: o pedido será criado uma única vez.

Preste atenção à formulação: a chave identifica a operação, não a requisição HTTP. Essa diferença será central mais adiante, quando analisarmos erros de implementação.

Mergulho profundo: o contrato do servidor e a anatomia de uma repetição segura

O contrato como acordo de comportamento

Idempotência não é um cabeçalho nem uma biblioteca. É um contrato em que o servidor promete ao cliente um comportamento específico em caso de repetição, e o cliente promete seguir as regras de formação de chaves. Um bom contrato responde às seguintes perguntas:

  1. Qual entidade é a unidade de idempotência: pedido, pagamento, linha do pedido, lote?
  2. Como o cliente envia a chave: cabeçalho, campo do corpo, parte da URL?
  3. O que acontece se a chave coincidir, mas o corpo da requisição for diferente?
  4. O que acontece se a primeira requisição ainda estiver em execução e chegar uma segunda com a mesma chave?
  5. Por quanto tempo o servidor guarda a chave?
  6. O que será retornado na repetição: a mesma resposta byte a byte ou o estado atual da entidade?
  7. Como a repetição se diferencia de uma nova requisição nos logs e nas métricas?

Se ao menos uma dessas perguntas não tiver resposta na documentação da API, o contrato está incompleto, e em situações indefinidas o comportamento dependerá da implementação, da versão e da fase da lua.

Três estados da chave

No servidor, cada chave tem um ciclo de vida de três estados. Entender esse ciclo explica noventa por cento dos problemas com duplicatas.

  • Ausente. A chave está sendo vista pela primeira vez. O servidor precisa reservá-la atomicamente e iniciar o processamento.
  • Em andamento (in-progress). A primeira requisição está sendo processada. Uma segunda requisição com a mesma chave não deve disparar um segundo processamento. Opções: retornar 409 Conflict pedindo para aguardar, bloquear até a conclusão da primeira e retornar seu resultado, ou retornar 202 Accepted com um link de status.
  • Concluída. O resultado está armazenado. A repetição retorna o resultado salvo, sem efeitos colaterais.

O erro de arquitetura mais comum é pular o estado intermediário. O desenvolvedor verifica "existe a chave no banco", não encontra, inicia o processamento, e uma repetição paralela faz o mesmo nesse mesmo instante. Dois fluxos, duas verificações, dois pedidos. A verificação e a reserva precisam ser uma única operação atômica: inserção com índice único, gravação condicional no Redis, transação com bloqueio.

Fingerprint da requisição

A chave identifica a operação, mas uma operação com qual conteúdo? Se o cliente, por causa de um bug, enviou a chave K com o valor de 1000 reais, e depois repetiu com a mesma chave e o valor de 10000, o que o servidor deve fazer? Retornar silenciosamente o resultado da primeira operação é perigoso: o cliente vai achar que pagou 10000. Executar a segunda viola a idempotência.

A resposta correta: o servidor guarda o fingerprint da requisição — um hash do corpo normalizado e dos cabeçalhos relevantes. Em uma repetição com a mesma chave, mas fingerprint diferente, retorna-se um erro 422 Unprocessable Content ou 400 com um código explícito do tipo idempotency_key_reused_with_different_payload. Isso protege contra erros lógicos do cliente e contra a falsificação de repetições.

Armazenamento da resposta: snapshot ou estado atual

Existem duas abordagens para o que retornar na repetição. Snapshot — o servidor guarda o status, os cabeçalhos e o corpo da resposta original e os devolve sem alterações. É estritamente idempotente e previsível. Estado atual — o servidor encontra a entidade criada pela chave e retorna sua representação atual. É mais conveniente se, entre as tentativas, o pedido passou para outro status, mas é menos previsível.

Em sistemas de pagamento predomina o snapshot: o cliente deve receber exatamente a resposta que teve na primeira tentativa. Em sistemas de gestão de pedidos, muitas vezes se aplica um híbrido: snapshot para códigos de erro, estado atual para sucesso. O importante é que a escolha esteja fixada no contrato.

O que o proxy muda no nível do contrato

Tecnicamente, o proxy não participa do contrato de idempotência: ele é transparente para cabeçalhos e corpo. Mas ele muda as probabilidades. Em uma conexão direta, a perda de resposta após execução bem-sucedida é raridade, uma fração de por cento de um por cento. Em uma cadeia com proxy móvel e rotação, esse evento se torna regular. Observamos integrações em que, com rotação de IP a cada cinco minutos, cerca de 0,3–0,8% das requisições terminavam em ruptura de conexão na fase de espera pela resposta. Com dez mil pedidos por dia, isso são trinta a oitenta duplicatas potenciais diariamente. Sem chave de idempotência, cada uma delas se transforma em uma duplicata real.

Há também uma segunda sutileza. Muitos servidores incluem na lógica de antifraude a verificação de "requisição repetida vinda de outro IP". Com a rotação do proxy móvel, a repetição quase sempre virá de um novo endereço. Se o servidor interpretar isso como atividade suspeita e rejeitar a repetição sem consultar o armazenamento de chaves, o cliente não receberá o resultado salvo e permanecerá na incerteza. Um bom contrato verifica a chave antes de qualquer heurística ligada à rede.

Método 1: geração e envio da chave de idempotência no lado do cliente

Onde a chave nasce

Regra de ouro: a chave é gerada uma única vez por operação de negócio, antes da primeira tentativa de envio, e armazenada junto com a intenção de executar a operação. Se a chave for criada dentro do cliente HTTP a cada chamada, a retentativa receberá uma nova chave e toda a proteção se anula. Esse erro é tão frequente que o destacaremos separadamente na seção de antipadrões, mas repetimos aqui: a chave vive no nível do serviço de pedidos, não no nível do transporte.

A sequência prática é esta:

  1. O usuário ou um processo interno inicia a criação do pedido.
  2. O serviço cria um registro local de "intenção de pedido" com status pending e gera a chave.
  3. A chave e o payload são salvos no banco local em uma única transação.
  4. Somente após o commit da transação é disparado o envio para a API externa via proxy.
  5. Todas as retentativas leem a chave do registro local, em vez de gerar uma nova.
  6. Após receber a resposta, o registro local é atualizado com o resultado e o identificador externo do pedido.

Essa ordem garante que, mesmo com o reinício do seu serviço no meio das retentativas, a chave não mudará: ela está no banco.

Formato da chave

A chave deve ser globalmente única e imprevisível para terceiros. Opções viáveis:

  • UUID versão 4 — clássico, 122 bits de aleatoriedade, serve em qualquer lugar.
  • UUID versão 7 ou ULID — contêm um timestamp nos bits mais significativos, o que os torna convenientes para ordenação e indexação no banco do servidor. Em 2026, já é a escolha padrão para novos sistemas.
  • Chave determinística a partir de um identificador natural — por exemplo, um hash do identificador do carrinho, do identificador do usuário e da versão do carrinho. Útil quando o cliente pode perder o estado e regenerar a chave a partir dos mesmos dados.

O que evitar: números sequenciais (fáceis de adivinhar a chave de outro e obter a resposta alheia), strings curtas, chaves que dependem apenas de tempo com baixa precisão.

Forma de envio

O padrão de fato é o cabeçalho Idempotency-Key. O rascunho de especificação da IETF fixa exatamente esse nome, e a maioria das APIs modernas o segue. Exemplo de chamada via proxy:

curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders

Algumas APIs aceitam a chave no corpo da requisição (campo client_reference_id, external_id, request_id). Também é uma opção viável, mas com uma sutileza: se o servidor usa o campo do corpo como chave, ele obrigatoriamente deve participar de um índice único, senão é apenas uma etiqueta, não uma proteção.

Escopo da chave

A chave deve ser única dentro de uma conta de cliente e de um endpoint. Um bom servidor compõe a chave interna de armazenamento como a combinação do identificador da conta, do método, do caminho e da chave enviada. Isso protege contra colisões entre clientes diferentes e contra o reuso acidental da chave para outra operação.

Checklist do lado do cliente

  • A chave é gerada antes da primeira tentativa e armazenada no banco junto com a intenção.
  • Todas as retentativas usam a mesma chave.
  • O corpo da requisição na retentativa coincide byte a byte com a primeira tentativa.
  • O cliente sabe tratar 409 (operação em andamento) como um sinal para esperar e repetir, e não como erro.
  • O cliente sabe tratar 422 com código de divergência de fingerprint como erro lógico que exige intervenção.
  • O cliente registra a chave em todos os logs relacionados à operação, para que as duplicatas possam ser investigadas.
  • O cliente não descarta a chave ao trocar de proxy, rotacionar IP ou mudar para um pool de reserva.

Método 2: implementação no servidor do armazenamento de chaves

Se você é dono do servidor que recebe via proxy as requisições dos seus clientes ou parceiros, esta seção é para você. Se você é apenas cliente, ela ajudará a avaliar a qualidade da implementação alheia pela documentação e pelo comportamento.

Esquema de armazenamento

A tabela ou estrutura mínima para as chaves contém os seguintes campos:

  • scope_key — chave composta: conta, método, caminho, Idempotency-Key enviada. Índice único.
  • fingerprint — hash do corpo normalizado da requisição.
  • state — um dos valores: in_progress, completed, failed.
  • response_status, response_headers, response_body — snapshot da resposta, preenchido na conclusão.
  • resource_id — identificador da entidade criada, se aplicável.
  • locked_at, completed_at, expires_at — marcas de tempo para tratamento de operações travadas e limpeza.

Reserva atômica

O coração da implementação é a operação que, em uma única ação, ou cria o registro em estado in_progress, ou informa que o registro já existe. Em banco relacional, isso é uma inserção com tratamento de conflito pelo índice único. No Redis, é o comando SET com os flags NX e EX, que grava o valor apenas se a chave não existir e já define o tempo de vida. Nada de "primeiro SELECT, depois INSERT": entre eles vai passar uma repetição paralela.

Pseudocódigo no nível da lógica:

  1. Calcular scope_key e fingerprint.
  2. Tentar inserir o registro com state = in_progress. Se a inserção for bem-sucedida, seguir para a execução da operação.
  3. Em caso de conflito: ler o registro existente.
  4. Se o fingerprint não coincidir — retornar 422 com código de divergência.
  5. Se state = in_progress — retornar 409 com cabeçalho Retry-After ou aguardar a conclusão (dentro de um timeout razoável).
  6. Se state = completed — retornar o snapshot salvo da resposta com um cabeçalho marcando a repetição, por exemplo Idempotent-Replayed: true.

Execução e gravação do resultado

Aqui está a segunda armadilha. A operação foi executada, o pedido foi criado, mas o processo caiu antes de gravar o resultado no armazenamento de chaves. O registro permanece em estado in_progress para sempre. A repetição recebe 409, depois outro 409, e assim indefinidamente.

Há três abordagens para resolver:

  • Transação única. A criação do pedido e a atualização do registro da chave são executadas em uma única transação de banco de dados. É a opção mais confiável, se o pedido e as chaves moram no mesmo banco.
  • Chave como parte da entidade. A chave de idempotência é armazenada diretamente na tabela de pedidos com índice único. Então o próprio pedido é o registro da chave; não é preciso uma tabela separada. Simples e confiável para casos com uma entidade por operação.
  • Recuperação de travadas. Um processo em background encontra registros in_progress mais antigos que um limite (por exemplo, 60 segundos), verifica se a operação foi de fato executada (por resource_id ou busca pela entidade) e ou conclui a gravação, ou move o registro para failed, permitindo a repetição.

Tratamento de erros da primeira tentativa

O que salvar se a primeira tentativa terminar em erro? Depende do tipo de erro. Erros de validação (400, 422) são determinísticos: repetir com o mesmo corpo dará o mesmo resultado, então podem ser cacheados. Erros de infraestrutura (500, 503, timeout de banco) não são determinísticos: se forem cacheados, o cliente nunca conseguirá executar a operação com sucesso. O comportamento correto: em caso de erro de infraestrutura, liberar a chave (excluir o registro ou mover para failed com possibilidade de reaquisição), para que a próxima repetição tente de novo.

Tempo de vida da chave

As chaves não podem ser armazenadas para sempre: a tabela vai inchar. Mas um prazo curto demais também é perigoso: se o cliente repetir meia hora após uma falha de rede, a chave deve continuar viva. A prática dos grandes provedores de pagamento converge para 24 horas como mínimo. Para pedidos de e-commerce, 24–72 horas são razoáveis. Para operações que o cliente pode repetir depois de falhas longas (por exemplo, sincronização de catálogo uma vez por dia), o prazo deve superar pelo menos o dobro do intervalo de sincronização.

Observabilidade

Cada repetição deve deixar rastro. Métricas que vale coletar: número de repetições que acertaram completed (repetições inofensivas), número de 409 (repetições concorrentes), número de 422 (divergência de fingerprint — quase sempre bug do cliente), idade do registro in_progress mais antigo (indicador de operações travadas). A razão entre repetições e operações únicas é uma medida direta da qualidade da rede entre cliente e servidor. Se ela cresce de repente, em algum lugar a qualidade do canal de proxy piorou ou a rotação mudou.

Checklist do lado do servidor

  • A reserva da chave é atômica.
  • Existe um estado separado in_progress e uma resposta clara para repetição concorrente.
  • O fingerprint do corpo é armazenado, e a divergência é rejeitada com erro explícito.
  • A gravação do resultado é transacional, ou existe um mecanismo de recuperação de registros travados.
  • Erros de infraestrutura não são cacheados; os determinísticos são.
  • O TTL é de pelo menos 24 horas e está documentado.
  • A repetição é marcada com um cabeçalho e aparece nas métricas.
  • A verificação da chave ocorre antes das heurísticas de rede do antifraude.

Método 3: protocolo de retentativas via proxy que não quebra a idempotência

A política de retentativas é tema de outro artigo, mas existe uma faixa estreita em que política de retentativas e idempotência se cruzam: quais sinais da cadeia de proxy significam que a repetição é necessária, e como a repetição não deve destruir o contrato. Vamos analisar isso.

Distinga falha do proxy de falha do upstream

Ao trabalhar via proxy, o cliente recebe erros de três origens, e é preciso reagir a eles de forma diferente:

  • Erros de conexão com o proxy. Não foi possível conectar ao proxy, o proxy retornou 407 (autenticação necessária), o proxy fechou a conexão antes de enviar a requisição. A requisição garantidamente não chegou ao servidor. Repetir é seguro até mesmo sem chave, mas com chave é melhor ainda.
  • Erros do proxy ao acessar o upstream. O proxy retornou 502 Bad Gateway ou 504 Gateway Timeout. Aqui a incerteza é máxima: 502 normalmente significa que o upstream não respondeu corretamente, mas pode ter executado a operação; 504 significa que o proxy cansou de esperar, e o servidor talvez ainda esteja processando. Repetir somente com chave.
  • Respostas do upstream que passaram pelo proxy. 500, 503, 429 do servidor de destino. A semântica é definida pelo contrato da API de destino. Repetir com chave segundo as regras da política de retentativas.

Merece atenção especial a ruptura da conexão durante a leitura da resposta. Os cabeçalhos já chegaram, o corpo foi interrompido. Esse é o caso mais traiçoeiro: você talvez tenha visto o status 201 Created, mas não recebeu o identificador do pedido no corpo. A repetição com chave retornará o snapshot completo da resposta. Sem chave, você obterá um segundo pedido e ainda por cima nunca saberá o identificador do primeiro.

Rotação de IP como evento, não como pano de fundo

Se o seu pool de proxies móveis rotaciona endereços por agendamento, sincronize o envio das operações críticas com as janelas de estabilidade. Uma técnica simples: perguntar à API do serviço de proxy quanto tempo falta para a próxima rotação e não iniciar a criação de um pedido se faltar menos que o seu timeout de espera pela resposta. Isso não substitui a idempotência, mas reduz o número de repetições e, portanto, a carga no armazenamento de chaves e no antifraude do parceiro.

Se a rotação acontece sob demanda, não chame a troca de IP entre tentativas de uma mesma operação sem necessidade. Algumas equipes fazem isso "para contornar travamento", mas o servidor, ao ver a mesma chave vinda de um novo endereço, pode ativar uma verificação adicional. A chave evitará a duplicata, mas a repetição pode ficar mais lenta.

Timeouts: duas fronteiras em vez de uma

Em conexão direta, normalmente se define um único timeout para a resposta. Via proxy, são necessários pelo menos dois: timeout de estabelecimento da conexão com o proxy (curto, unidades de segundos) e timeout de espera pela resposta do upstream (mais longo, considerando o tempo de processamento do pedido). Se forem unificados em um só, um timeout curto disparará constantemente em processamentos lentos, gerando repetições desnecessárias, e um longo fará você esperar segundos extras por um proxy indisponível.

Importante: o timeout de espera pela resposta não deve ser menor que o tempo real de criação do pedido no servidor. Caso contrário, você sistematicamente vai interromper a conexão exatamente no momento do processamento, e cada operação se transformará em um par "tentativa interrompida mais repetição". A chave protegerá contra duplicatas, mas o servidor gastará recursos processando em vão.

Repetição através de outro proxy

Uma estratégia razoável: a primeira tentativa de repetição passa pelo mesmo proxy (talvez a conexão só tenha piscado), a segunda passa por outro proxy do pool (talvez o problema esteja naquele canal específico). A chave não muda. O corpo não muda. Só o caminho muda. Assim você separa problemas de rede de problemas da própria requisição e obtém informação de diagnóstico: se passou de imediato pelo segundo proxy, o problema estava no canal.

Protocolo passo a passo da repetição segura

  1. Ler a chave e o corpo do registro local de intenção.
  2. Enviar a requisição pelo proxy atual, com dois timeouts.
  3. Em caso de sucesso: salvar o resultado, encerrar.
  4. Em caso de 409 do servidor: aguardar o tempo indicado ou um intervalo razoável, repetir com a mesma chave.
  5. Em caso de 422 com código de divergência de fingerprint: parar, abrir incidente, não repetir automaticamente.
  6. Em caso de erro de conexão com o proxy: trocar de proxy, repetir imediatamente.
  7. Em caso de 502, 504, ruptura ou timeout: aplicar a política de atraso, repetir com a mesma chave; a partir da segunda repetição — por outro proxy.
  8. Depois de esgotar as tentativas: deixar o registro em estado unknown e encaminhar para a fila de conciliação (ver Método 4).

O item oito é crítico. O estado "não sei se o pedido foi criado" é um estado legítimo, e não pode ser silenciosamente colapsado nem em "criado" nem em "não criado".

Método 4: quando o servidor não suporta chaves de idempotência

O mundo ideal acaba na primeira API de parceiro cuja documentação não menciona a palavra "idempotência". O que fazer se você é cliente e o servidor simplesmente cria um pedido a cada POST? Existem várias técnicas, das simples às arquiteturais.

Chave natural em campos da requisição

Muitas APIs, sem ter um Idempotency-Key formal, aceitam um campo como external_order_id, client_reference, merchant_order_number e prometem unicidade por ele dentro da conta. Isso é idempotência com outro nome. Confira a documentação e, principalmente, confira o comportamento: envie duas requisições com o mesmo identificador externo em ambiente de teste e veja se retorna erro de duplicata ou se cria uma segunda entidade. As promessas da documentação e o comportamento real divergem mais do que se gostaria.

Leitura antes da repetição

Se o servidor oferece a possibilidade de buscar entidades pelo seu identificador externo ou por parâmetros (por exemplo, lista de pedidos com filtro por tempo e valor), então antes de cada repetição faça uma requisição de verificação: o pedido com as minhas características já apareceu? Isso não dá garantia estrita (entre a verificação e a repetição pode haver uma janela), mas reduz a probabilidade de duplicata em uma ordem de grandeza. O esquema:

  1. A primeira tentativa terminou de forma indefinida.
  2. Aguardar um intervalo suficiente para a conclusão do processamento no servidor.
  3. Executar um GET com filtro por identificador externo ou combinação única de campos.
  4. Se o pedido for encontrado — registrar o identificador, a repetição não é necessária.
  5. Se não for encontrado — repetir o POST.

Para que a busca funcione, inclua no pedido uma marca pela qual ele possa ser encontrado: comentário, campo customizado, número único da posição. Mesmo que o servidor ignore isso como chave, ele devolverá a marca na resposta, e você poderá conferir.

Divisão da operação em reserva e confirmação

Algumas APIs suportam modelo bifásico: primeiro se cria um rascunho ou hold (operação que pode ser repetida ou cancelada com segurança), depois a confirmação pelo identificador do rascunho. A confirmação por identificador é idempotente por natureza: não se pode confirmar o mesmo rascunho duas vezes. Se esse modelo estiver disponível, ele é preferível à criação em uma única etapa mesmo com chaves, porque reduz a janela de incerteza do passo mais arriscado.

Padrão Outbox do seu lado

Mesmo que o servidor não garanta nada, você pode garantir que do seu lado cada operação saia com exatamente uma intenção. O Outbox transacional é uma tabela de operações de saída na qual o registro entra na mesma transação da mudança de negócio (por exemplo, com a mudança do carrinho para o status "em processamento de checkout"). Um processo separado de envio retira registros do Outbox e executa as requisições via proxy. Cada registro tem um identificador único, que você usa como chave ou como external_id. Mesmo que o remetente caia no meio do trabalho, o registro permanecerá no Outbox, e a repetição irá com o mesmo identificador.

Conciliação como última linha de defesa

Reconciliation, ou conciliação, é um processo regular que compara a lista das suas operações com a lista de entidades do lado do parceiro e encontra divergências: pedidos que existem no parceiro, mas não estão vinculados do seu lado; operações em status unknown; duplicatas por características coincidentes. A conciliação não evita a duplicata, mas a encontra em minutos, e não em um mês depois, no relatório da contabilidade. Para operações via canais instáveis, isso é componente obrigatório, não opção.

Prática: rodar a conciliação a cada 10–15 minutos para operações mais antigas que o seu timeout máximo de retentativas, vincular automaticamente as entidades encontradas aos registros em unknown e encaminhar as duplicatas detectadas para uma fila de cancelamento com confirmação manual, se o valor ultrapassar um limite.

Saga e compensações

Se o pedido faz parte de uma cadeia de ações (reserva de estoque, pagamento, entrega), uma duplicata em um elo quebra toda a cadeia. O padrão saga pressupõe que cada passo tenha uma ação compensatória: cancelamento do pedido, estorno do pagamento, liberação da reserva. A compensação também precisa ser idempotente, senão você estará lutando contra duplicatas de cancelamento. Ao projetar a integração, já escreva os pares "ação — compensação" e verifique em ambos se a repetição é segura.

Erros típicos: como as equipes criam duplicatas por conta própria

Erro 1. A chave é gerada dentro do cliente HTTP

O mais comum. Um wrapper sobre a biblioteca HTTP adiciona o cabeçalho Idempotency-Key com um novo UUID a cada chamada. O mecanismo de retentativas dentro da mesma biblioteca chama o envio de novo — e recebe uma nova chave. Externamente parece tudo certo: o cabeçalho está lá. Na prática, não há proteção. Verifique nos logs do servidor ou do proxy se as chaves coincidem nas repetições.

Erro 2. A chave muda junto com o corpo ao "corrigir" a requisição

O cliente recebeu 400 por causa de um campo inválido, corrigiu o campo e repetiu com a mesma chave. O servidor com verificação de fingerprint retornará 422. O servidor sem verificação retornará o erro 400 cacheado, e o cliente ficará batendo em uma parede. Uma requisição corrigida é uma nova operação, e ela precisa de uma nova chave.

Erro 3. Verificação da chave via SELECT, depois INSERT

Já analisado acima, mas repetimos: entre a leitura e a gravação passa uma repetição paralela. Isso se manifesta especialmente ao trabalhar via proxy, porque os timeouts do cliente geram repetições com intervalo de unidades de segundos, e o processamento do pedido leva o mesmo tanto. Só reserva atômica.

Erro 4. Idempotência por IP ou sessão

O servidor "lembra" que aquele mesmo IP acabou de fazer uma requisição igual e rejeita a repetição. Com a rotação do proxy móvel, a repetição chega de outro endereço, e a proteção não atua. O inverso também é ruim: pedidos diferentes e legítimos do mesmo endereço de proxy (você tem vários clientes atrás do mesmo IP) são rejeitados como duplicatas. A chave deve ser explícita e enviada pelo cliente.

Erro 5. TTL curto demais

As chaves vivem cinco minutos, "para não sujar o Redis". A falha de rede dura vinte minutos. A fila de retentativas chega à operação meia hora depois. A chave já foi esquecida, o pedido é criado uma segunda vez. O TTL deve cobrir o cenário realista mais longo de repetição adiada.

Erro 6. Cache de erros de infraestrutura

A primeira tentativa falhou com 500 por indisponibilidade temporária do banco. O servidor salvou o 500 como resultado por chave. Todas as repetições seguintes recebem 500 do cache, embora o banco já tenha voltado. O cliente é obrigado a mudar a chave, perdendo o vínculo com a operação original. Só resultados determinísticos podem ser cacheados.

Erro 7. Colapsar o estado unknown

Depois de esgotar as tentativas, o cliente marca a operação como failed e permite ao usuário fazer o pedido de novo. Mas o servidor executou a primeira operação. O usuário fica com dois pedidos e uma cobrança dupla. O estado unknown deve existir explicitamente e ser resolvido pela conciliação, e não por uma suposição otimista.

Erro 8. Repetir operações não idempotentes "porque é mais simples"

Uma camada universal de retentativas repete todas as requisições do mesmo jeito, incluindo POSTs sem chave. Isso funciona até a primeira tempestade de rede, depois da qual surgem centenas de duplicatas em uma hora. A camada de retentativas precisa saber quais requisições podem ser repetidas e se recusar a repetir as não idempotentes sem chave explícita.

Erro 9. Uma chave para o lote inteiro

O cliente envia um array de cem pedidos com uma única chave. O servidor processou sessenta e caiu. A repetição com a mesma chave recebe 409 ou um snapshot parcial. Como saber quais quarenta precisam ser criados? Para lotes, é preciso ou uma chave por posição, ou uma garantia do servidor de atomicidade do lote inteiro, ou uma resposta com status por elemento. Sem isso, lotes via canal instável são fonte de caos.

Erro 10. Ausência da chave nos logs

A duplicata aconteceu, e você tenta entender se foi uma repetição com a mesma chave (bug do servidor) ou duas operações diferentes (bug do cliente). Nos logs não há chave. A investigação vira adivinhação. A chave deve estar em cada linha de log dos dois lados e no journal do proxy, se o serviço de proxy suportar log de cabeçalhos.

Ferramentas e recursos para implementação

Do lado do cliente

  • Bibliotecas de identificadores. Geradores de UUIDv7 e ULID existem para todas as principais linguagens. Escolha os que garantem monotonicidade dentro do milissegundo, se as chaves entrarem em índices do banco do servidor.
  • Clientes HTTP com timeouts separados. Certifique-se de que seu cliente permite definir separadamente o timeout de conexão com o proxy e o timeout de leitura da resposta. A maioria dos clientes modernos consegue, mas por padrão muitas vezes há um timeout único.
  • Filas com garantia de entrega. Para implementar o Outbox serve qualquer sistema de broker com confirmação de processamento. É importante que o identificador da mensagem seja estável entre reentregas — ele é útil como base da chave.
  • API de gerenciamento de proxy. Serviços de proxy móvel de qualidade têm uma interface programática que permite saber o estado do canal, o tempo até a rotação e trocar o IP sob demanda. Integrar-se a essa API permite não iniciar operações críticas antes da rotação e mudar conscientemente o caminho entre tentativas.

Do lado do servidor

  • Banco relacional com índices únicos. A opção mais confiável para o armazenamento de chaves, se os volumes permitirem. A inserção com tratamento de conflito é uma operação atômica nativa.
  • Redis ou similar. Para sistemas de alta carga: SET com os flags NX e EX para reserva, chave separada para o snapshot da resposta. Lembre-se do risco de perda de dados na queda de um nó e configure a persistência.
  • Middleware de idempotência. Para frameworks web populares existem camadas intermediárias prontas que implementam o contrato básico: reserva, fingerprint, snapshot. Verifique como se comportam em repetições concorrentes e em queda entre execução e gravação — é justamente aí que as boas implementações se diferenciam das formais.
  • Gateways de API. Alguns gateways conseguem fazer deduplicação pelo cabeçalho na entrada. Isso alivia a carga da aplicação, mas o gateway normalmente não conhece o resultado de negócio e pode cachear erros de infraestrutura. Use como primeiro filtro, não como proteção única.

Testes

  • Injeção de falhas de rede. Ferramentas de proxy para testes que conseguem romper a conexão após o envio da requisição, mas antes da resposta, atrasar a resposta além do timeout, retornar 502 e 504. Sem esses testes, você não verá o comportamento do sistema no cenário mais importante.
  • Testes concorrentes. Envio simultâneo de N requisições com a mesma chave. Resultado esperado: exatamente uma entidade criada, N-1 respostas 409 ou snapshots. Qualquer outro resultado é defeito.
  • Teste de reinício no meio da operação. Matar o processo após a criação do pedido, mas antes da gravação da chave. Verificar se o mecanismo de recuperação de registros travados funcionou.
  • Teste de rotação. Primeira tentativa por um IP, repetição por outro. Verificar se o servidor retornou o snapshot em vez de rejeitar a repetição por heurística.

Padrões e documentos

O rascunho de especificação da IETF sobre o cabeçalho Idempotency-Key é o ponto de partida para formular o contrato: nele estão definidos o nome do cabeçalho, a semântica de conflitos e os códigos de resposta recomendados. A documentação pública dos grandes provedores de pagamento é um bom modelo de como descrever um contrato para integradores externos: TTL, comportamento em divergência de corpo, tratamento de requisições concorrentes. A seção sobre métodos idempotentes na especificação de semântica do HTTP explica por que PUT e DELETE podem ser repetidos e POST não — vale reler antes de projetar endpoints.

Casos e resultados

Caso 1. Agregador de pedidos e 47 duplicatas por mês

Uma empresa agregadora enviava pedidos para o sistema de um parceiro logístico através de um pool de proxies móveis com rotação a cada cinco minutos. O volume era de cerca de 12 mil pedidos por dia. Não havia chaves de idempotência: a API do parceiro não as documentava. As duplicatas eram descobertas uma vez por mês pela conciliação financeira, e cada uma custava em média 900 reais em cancelamento, estorno e trabalho manual.

O diagnóstico pelos logs do proxy mostrou: 0,4% das requisições terminavam em ruptura de conexão após o envio do corpo e antes de receber a resposta, principalmente nos minutos de rotação. A repetição acontecia após três segundos, e em 30% dos casos a primeira tentativa já havia sido executada nesse momento. A conta batia com as duplicatas observadas.

A solução em três passos. Primeiro, descobriu-se que a API do parceiro aceitava o campo external_id e rejeitava duplicatas por ele, embora isso estivesse mencionado em uma única linha da documentação. O campo passou a ser preenchido com um identificador estável do Outbox local. Segundo, as janelas de rotação foram sincronizadas com o envio: novos pedidos não eram enviados nos 15 segundos antes da rotação. Terceiro, foi adicionada uma conciliação a cada 10 minutos. Resultado no trimestre: zero duplicatas, número de repetições caiu 70% graças à sincronização com a rotação, o tempo médio de checkout subiu 1,2 segundo por causa da espera pelas janelas — preço aceitável.

Caso 2. Serviço de pagamento e retentativas concorrentes

Um serviço fintech implementou idempotência do seu lado: o cabeçalho era aceito, a chave era salva no banco, e na repetição retornava-se o snapshot. Ainda assim, duplicatas apareciam, raras, mas regulares: cerca de uma a cada 40 mil operações. A investigação mostrou que a verificação da chave era feita por leitura e depois por gravação, e clientes com timeouts agressivos (duas repetições em um segundo por proxies diferentes) caíam na janela entre elas.

Substituiu-se por inserção com índice único e adicionou-se o estado in_progress com resposta 409 e cabeçalho Retry-After de um segundo. Adicionou-se a métrica de repetições concorrentes. Ela revelou algo inesperado: 2% de todas as operações recebem pelo menos um 409, ou seja, os clientes repetem muito mais agressivamente do que se supunha. O serviço atualizou a documentação com recomendações de timeout, e em dois meses a fração de 409 caiu para 0,3%. Duplicatas: zero em meio ano.

Caso 3. Integração com marketplace e lotes

Um vendedor carregava estoques e preços em um marketplace em lotes de 500 posições via proxy. A idempotência do lote estava no nível da requisição inteira. Em caso de ruptura de conexão, a repetição ou era rejeitada (lote em andamento) ou retornava o snapshot de um resultado parcial, do qual não dava para saber quais posições foram atualizadas. O vendedor concluía "não atualizou" e carregava de novo, o que criava corridas entre o lote antigo e o novo.

Solução: migrar para lotes com identificadores de operação por elemento e pedir o status por elemento após uma conclusão indefinida. O tamanho do lote foi reduzido para 100 posições, para que o tempo de processamento não ultrapassasse o timeout. O número de atualizações "travadas" caiu de dezenas por dia para zero, e as divergências de estoque, que antes causavam regularmente cancelamentos de pedidos de compradores, desapareceram.

Caso 4. Agente automatizado e retentativas em cadeia

Tendência de 2026: cada vez mais integrações são executadas por agentes autônomos baseados em grandes modelos de linguagem, que chamam APIs seguindo instruções. Uma equipe implementou um desses agentes para fazer compras de fornecedores. Diante de uma resposta indefinida, o agente "raciocinava" e decidia repetir a operação, gerando uma nova requisição. Não havia chaves, porque o agente formava a chamada do zero a cada vez. Na primeira semana — 11 duplicatas de compras.

Correção: o agente foi proibido de formar requisições de criação diretamente. Ele cria o registro de intenção no Outbox por meio de uma ferramenta interna, e o envio é feito por um serviço determinístico com chaves e conciliação. O agente só recebe o status final. As duplicatas desapareceram e, de quebra, surgiu uma rastreabilidade completa de quem e por que iniciou cada compra. A conclusão geral: sistemas autônomos com capacidade de retentativa são uma nova e poderosa fonte de duplicatas, e a barreira de idempotência é obrigatória para eles.

FAQ: perguntas difíceis sobre idempotência e retentativas

É preciso chave de idempotência para PUT e DELETE, se eles são idempotentes por especificação?

Formalmente, não: repetir um PUT com o mesmo corpo produzirá o mesmo estado. Mas há nuances. Se o PUT retorna 201 ao criar e 200 ao atualizar, a repetição retornará um status diferente, e o cliente pode interpretá-lo de outra forma. O DELETE na repetição retornará 404 em vez de 204, o que muitas vezes é tratado como erro. A chave com snapshot da resposta torna o comportamento previsível. Além disso, se o PUT causa efeitos colaterais (envio de notificação, gravação de auditoria), eles serão executados de novo. Idempotência do método não é igual à idempotência de todos os efeitos colaterais.

O que fazer se o servidor retornou 409 in_progress, mas a primeira tentativa na verdade morreu?

Essa é uma responsabilidade do servidor: ele deve ter um mecanismo de recuperação de registros travados com limite de tempo. O cliente deve esperar o 409 não infinitamente, mas um número limitado de vezes (por exemplo, até dois minutos) e então mover a operação para unknown e encaminhá-la à conciliação. Se o servidor mantém in_progress por mais tempo que o razoável de forma sistemática, é um defeito de implementação que deve ser comunicado ao dono da API.

Como lidar com a chave se a requisição passa por vários proxies em cadeia?

Nada de especial: a chave é enviada no cabeçalho e passa transparentemente por qualquer cadeia. A única coisa que vale conferir é se algum nó intermediário remove cabeçalhos não padronizados. Alguns gateways corporativos filtram cabeçalhos por lista branca. Teste simples: enviar uma requisição por toda a cadeia para um endpoint de debug próprio e confirmar que o cabeçalho chegou.

Posso usar o hash do corpo da requisição como chave e não guardar nada no cliente?

Pode, mas com ressalvas. Dois pedidos diferentes com o mesmo conteúdo (mesmo produto, mesmo valor, mesmo comprador) receberão a mesma chave, e o segundo será rejeitado como repetição. Para evitar isso, adiciona-se ao corpo um componente único — identificador do carrinho ou número sequencial local. Então o hash do corpo se torna uma chave determinística da operação. Essa abordagem é conveniente para clientes sem armazenamento local confiável, mas exige normalização estrita do corpo: mudar a ordem dos campos no JSON altera o hash.

Quanto tempo esperar antes de repetir para dar tempo de o servidor concluir a primeira tentativa?

Isso é uma questão de política de retentativas, mas do ponto de vista do contrato uma coisa importa: se o servidor suporta in_progress com 409, não é preciso esperar "no olhômetro" — o servidor avisa que a operação ainda está em execução. Se o servidor não tem esse estado, o intervalo antes da repetição deve superar o percentil 99 do tempo de processamento da operação no servidor. Dá para descobrir isso na documentação, nas métricas de requisições bem-sucedidas ou empiricamente em ambiente de teste.

Vale a pena tornar idempotentes as operações de leitura?

GET é idempotente por definição, não precisa de chave. Mas há uma exceção: "leitura com efeito colateral", por exemplo um GET que marca uma notificação como lida ou consome um limite. Isso é um cheiro arquitetural; essas operações é melhor transformar em POST com chave do que acoplar idempotência ao GET.

O que fazer com as chaves em migração ou troca de versão da API?

Inclua a versão do endpoint no escopo da chave no servidor. Assim, uma chave usada na v1 não colidirá com a mesma chave na v2. Para o cliente, a regra é simples: migração é composta de novas operações com novas chaves, as chaves antigas não são transferidas. Se uma operação estava em unknown no momento da migração, resolva-a primeiro pela conciliação, depois migre.

Como explicar ao negócio por que vale gastar um sprint em idempotência, se duplicatas "quase não acontecem"?

Calcule o custo de uma duplicata: cancelamento, estorno, suporte, reputação, às vezes multas do parceiro. Multiplique pela frequência observada. Depois mostre que a frequência cresce de forma não linear em incidentes de rede: em um dia calmo, zero duplicatas; em um dia de falha da operadora de telecom, centenas em uma hora. Idempotência é um seguro com prêmio conhecido e ganho desconhecido, mas potencialmente enorme. Além disso, ela tem um efeito colateral: a possibilidade de repetir requisições de forma agressiva sem medo, o que acelera a recuperação após falhas.

A idempotência aumenta a carga no servidor?

De forma insignificante: uma gravação e uma leitura adicionais por operação. Em troca, ela reduz a carga em cenários de falha, porque a repetição retorna o snapshot em milissegundos em vez de reprocessar o pedido inteiro. Sob uma tempestade de repetições, um servidor com idempotência aguenta melhor a carga do que um sem ela — é contraintuitivo, mas confirmado na prática.

Conclusão: contrato em vez de esperança

Vamos reunir o essencial. Qualquer rede entrega requisições segundo o princípio de "pelo menos uma vez". Proxies — especialmente os móveis, com rotação e canal de rádio — fazem da repetição não uma raridade, mas a norma. A política de retentativas responde à pergunta "quando e como repetir". A idempotência responde à pergunta "por que a repetição não vai quebrar nada". Sem a segunda resposta, a primeira é perigosa.

A repetição segura se sustenta em três pilares. Chave da operação, nascida antes da primeira tentativa e viva no seu banco, não no cliente HTTP. Contrato do servidor com reserva atômica, estado in_progress, fingerprint do corpo, snapshot da resposta e TTL razoável. Conciliação como última linha de defesa para operações presas em incerteza. Se o servidor não oferece contrato, o papel da chave passa a ser desempenhado por um identificador natural, e o do armazenamento, pelo seu Outbox.

O que fazer a seguir, ainda hoje:

  1. Encontre nas suas integrações todas as operações POST que são repetidas automaticamente. Para cada uma, responda: existe chave, onde ela é gerada, ela coincide nas retentativas?
  2. Leia a documentação das APIs parceiras em busca de campos external_id e do cabeçalho Idempotency-Key. Verifique o comportamento no ambiente de teste com duas requisições idênticas.
  3. Adicione o estado unknown ao modelo de operações e um processo de conciliação para ele.
  4. Se você é dono do servidor, rode três testes: repetições concorrentes, queda entre execução e gravação, repetição de outro IP.
  5. Coloque no dashboard a razão entre repetições e operações únicas. É o seu indicador de saúde do canal via proxy.

Idempotência é um caso raro em que a disciplina de engenharia se converte diretamente em tranquilidade para o negócio. Um contrato projetado uma vez protege durante anos contra duplicatas, tempestades de repetições e ligações noturnas da contabilidade. E, sinceramente, há um prazer especial em olhar para um gráfico de milhares de repetições por um canal instável e ver na coluna de duplicatas um firme zero.