Resposta direta

Idempotência, retentativas e conciliação não são funções isoladas. Elas formam uma cadeia de tratamento de falhas: identificadores estáveis reconhecem a mesma intenção de negócio; a semântica idempotente define se a retentativa é segura; tentativas limitadas lidam com falhas transitórias; a conciliação verifica se a solicitação e o efeito financeiro final são coerentes; e o escalonamento manual resolve estados que o sistema não consegue determinar com segurança.

O erro mais perigoso é concluir que “timeout significa falha, então basta enviar de novo”. O servidor pode ter concluído a operação e a resposta pode ter se perdido na rede. Para o chamador, o estado é desconhecido — não uma falha confirmada. Sem idempotência ou consulta de estado bem definida, a retentativa pode criar sessões, transferências ou lançamentos duplicados.

Cinco conceitos que não devem ser confundidos

Conceito Definição O que não garante sozinho
Identificador único Valor estável que relaciona solicitação, transação, rodada ou aposta A existência do campo não prova que o servidor elimina duplicidades
Idempotência Repetir a mesma intenção produz o mesmo efeito final esperado de executá-la uma vez Não exige texto de resposta idêntico nem impede falhas
Retentativa (retry) Nova tentativa dentro de condições, quantidade e tempo limitados Não transforma erro permanente em sucesso nem substitui consulta de estado
Conciliação Compara intenção, resultado, transações, rodadas e movimentações financeiras Não decide automaticamente toda compensação
Escalonamento manual Pessoas autorizadas investigam e decidem quando a automação não consegue concluir Não deve compensar falta de logs ou de protocolo por suposição

O método HTTP também não decide a semântica de negócio. O RFC 9110 define PUT, DELETE e métodos seguros como idempotentes e orienta cautela ao repetir automaticamente solicitações não idempotentes. Como a referência pública mostra chamadas da plataforma via POST, não se pode presumir uma retentativa segura apenas pelo método.

1. Diferencie o identificador de rastreamento do identificador de negócio

Uma solução confiável normalmente precisa de pelo menos:

  • identificador de rastreamento da solicitação: conecta a tentativa aos logs, à resposta e à investigação;
  • identificador da transação de negócio: representa a intenção e conecta transferência, movimentação, rodada ou aposta.

A referência pública mostra reqTraceId e, em determinados fluxos, merchantTransactionId, transactionId, roundId e betId. O merchantTransactionId é apresentado como identificador único para conciliação.

Esses campos oferecem pontos de correlação, mas não comprovam que todos os endpoints deduplicam solicitações, qual é o escopo ou prazo da deduplicação, como conflitos de parâmetros são tratados ou se uma retentativa retorna o resultado original. Tudo isso precisa constar no protocolo e ser testado.

O draft-ietf-httpapi-idempotency-key-header-07 propôs o cabeçalho Idempotency-Key, mas estava arquivado como expirado em 2026-08-09 e não se tornou RFC. Ele é apenas referência histórica de desenho; não comprova suporte da AG ao cabeçalho.

2. Repita somente operações e falhas adequadas

Uma retentativa automática exige que a falha seja transitória e que repetir a operação seja seguro no protocolo em vigor.

Cenário Princípio padrão Condição antes de uma retentativa automática
Consulta ou lista sem efeito colateral Considerar tentativas limitadas Protocolo confirma leitura sem efeitos e falha transitória
Criação de sessão Não recriar só por timeout Idempotência clara ou consulta da sessão pelo identificador original
Alteração de carteira ou transferência Consultar estado ou conciliar primeiro Identificador, escopo idempotente e resposta a duplicidade confirmados
Callback O consumidor identifica eventos repetidos Evento ou transação estável acordado entre as partes
Erro de parâmetro, permissão ou assinatura Não repetir a mesma solicitação Corrigir parâmetro, acesso, relógio ou credencial antes de nova decisão
Timeout ou desconexão Marcar como estado desconhecido Consultar pelo identificador original; repetir apenas se a semântica for segura

Defina timeout por tentativa, número máximo, orçamento total e condição de parada. Este artigo não fixa valores; eles dependem do risco, do protocolo e dos limites dos sistemas envolvidos.

3. Backoff exponencial e jitter reduzem novas ondas de carga

Quando a tentativa é segura, use backoff exponencial com limite e jitter. O intervalo cresce a cada tentativa até um teto; a aleatoriedade distribui clientes que, sem isso, voltariam todos ao mesmo tempo.

AWS e Google documentam esse princípio, mas também ressaltam que a operação precisa ser idempotente e o erro, repetível. Backoff não torna uma gravação não idempotente segura e não substitui um orçamento total.

Evite:

  • retentativa imediata ou sem limite;
  • a mesma política para todo erro HTTP e de negócio;
  • retentativas independentes no gateway, SDK, serviço e fila, multiplicando tentativas;
  • gerar um novo identificador de negócio a cada tentativa;
  • registrar chaves, credenciais completas ou dados sensíveis desnecessários;
  • continuar indefinidamente após falhas consecutivas.

4. Não renomeie estado desconhecido como falha

Quando uma solicitação foi enviada, mas o resultado de negócio não chegou por completo, mantenha um estado UNKNOWN:

NEW -> SENT -> CONFIRMED_SUCCESS
            -> CONFIRMED_FAILURE
            -> UNKNOWN -> QUERY_OR_RECONCILE -> CONFIRMED_SUCCESS
                                           -> CONFIRMED_FAILURE
                                           -> MANUAL_REVIEW

Em UNKNOWN, consulte o resultado, a transação ou a movimentação usando o identificador original. Se não houver fonte de consulta confiável, interrompa ações automáticas que possam duplicar efeitos, preserve o contexto e escale. Os nomes de estados e interfaces acima são um método geral, não uma descrição da implementação atual da AG.

5. Concilie evidências independentes

Para fluxos de carteira, aposta ou prêmio, relacione:

  • intenção original e identificador de rastreamento;
  • identificador de transação da plataforma cliente;
  • identificadores da contraparte, da rodada e da aposta;
  • valor, moeda, direção e interpretação de horário;
  • resultado de negócio da API e registros posteriores;
  • movimentação da carteira, saldo e estado final.

Classifique o resultado como consistente, falha confirmada, duplicidade, diferença de valor ou moeda, registro ausente ou estado desconhecido. Cada divergência precisa de responsável, evidência, autoridade de compensação e condição de fechamento. Reenviar uma movimentação financeira não é conciliar.

Frequência, retenção e tolerâncias dependem do risco, volume, modelo de carteira e contrato; este texto não define métricas da AG.

6. Quando o tratamento deve ser manual

Pare a automação e crie um escalonamento auditável quando:

  • o orçamento de tentativas terminou e o estado continua incerto;
  • o mesmo identificador aparece com valor, moeda, conta ou parâmetro crítico diferente;
  • resposta, registro e movimentação da carteira se contradizem;
  • a fonte autoritativa ou os logs exigidos não estão disponíveis;
  • há suspeita de débito ou prêmio duplicado, acesso indevido ou evento de segurança;
  • uma compensação automática pode ampliar impacto financeiro, regulatório ou ao cliente.

Registre identificadores, linha do tempo, ações, evidências, avaliação de risco, aprovador e resultado final — sem inserir segredos em chamados.

Checklist de implementação

  • Separar identificadores de rastreamento e de transação de negócio.
  • Definir escopo idempotente, conflitos e resposta a duplicidade para operações com efeitos.
  • Separar falha transitória, falha permanente e estado desconhecido.
  • Repetir automaticamente apenas operações comprovadamente seguras.
  • Aplicar timeout, orçamento total, teto de backoff e jitter.
  • Impedir retentativas multiplicadas em várias camadas.
  • Consultar ou conciliar pelo identificador original em estado desconhecido.
  • Relacionar transação, rodada, valor, moeda e movimentação.
  • Definir condição de parada e responsável pelo escalonamento.
  • Testar timeout, resposta perdida, duplicidade e divergência em staging.

Escopo atual e limites

A referência pública apresenta identificadores de solicitação, transação, rodada e aposta e orienta interpretar o resultado no corpo, não apenas pelo HTTP. Consultas de registros podem ajudar a desenhar rastreabilidade e conciliação. O desenho efetivo depende do modelo de carteira e do protocolo formal.

Não se afirma que todos os POST da AG sejam idempotentes, que Idempotency-Key seja suportado, nem se definem escopo de deduplicação, retenção, resposta a conflito, quantidade de tentativas, backoff ou periodicidade. Também não se prometem zero duplicidade, zero perda, consistência absoluta, segurança absoluta, desempenho ou SLA.

Perguntas frequentes

Posso repetir automaticamente um POST que falhou?

Não apenas por ele ter falhado. Primeiro, determine se a falha é transitória, se a operação pode ter produzido efeito e se o protocolo oferece idempotência ou consulta pelo identificador original.

Timeout significa que a transação falhou?

Não. O servidor pode não ter iniciado, estar processando, ter concluído ou ter falhado. Consulte ou concilie usando o identificador original.

Um ID único já implementa idempotência?

Não. É preciso saber como o servidor armazena e compara o ID, seu escopo e prazo, como trata parâmetros conflitantes e o que responde à repetição.

Devo gerar um novo ID em cada tentativa?

Depende de como o protocolo distingue intenção de negócio e tentativa de transporte. Em geral, o identificador de negócio permanece estável; a regra do identificador de rastreamento deve ser acordada.

Leituras relacionadas e próximo passo

Para discutir um desenho específico, informe em “Fale conosco” o modelo de carteira, a direção das chamadas, as operações críticas e a capacidade atual de conciliação. Isso não antecipa comportamento de produção.

Fontes e aplicabilidade

Os princípios vêm do RFC 9110, do rascunho arquivado de Idempotency-Key, dos artigos da AWS sobre APIs idempotentes e backoff com jitter e da estratégia de retentativa do Google Cloud. Eles explicam métodos gerais; não confirmam algoritmo, parâmetro ou cabeçalho implementado pela AG.

Precisa transformar estas orientações em um plano de projeto?

Este artigo apoia a avaliação do projeto e não substitui a validação técnica, contratual, de certificação ou da legislação local.

Fale conosco