A resposta curta

Idempotência, retentativas e reconciliação não são três recursos independentes. Elas formam uma única cadeia de tratamento de falhas: identificadores estáveis reconhecem a mesma intenção de negócio; a semântica de idempotência determina se a repetição é segura; retentativas limitadas tratam falhas transitórias; a reconciliação compara as solicitações com o resultado financeiro final; e o escalonamento manual trata estados que a automação ainda não consegue resolver.

A suposição mais perigosa é “um timeout significa falha, então envie novamente”. Um servidor pode concluir uma solicitação mesmo quando sua resposta se perde em trânsito. Nesse caso, o chamador tem um estado desconhecido, e não uma falha confirmada. Sem semântica explícita de idempotência ou de consulta, uma retentativa automática pode criar uma sessão, transferência ou lançamento contábil duplicado.

Cinco conceitos a separar

Conceito Definição de trabalho O que ele não garante por si só
Identificador estável Um valor durável que correlaciona a mesma solicitação, transação, rodada ou aposta A presença de um ID não comprova deduplicação no lado do servidor
Idempotência Espera-se que repetir a mesma intenção de negócio tenha o mesmo efeito final que processá-la uma vez As respostas não precisam ser textualmente idênticas, e a solicitação ainda pode falhar
Retentativa Outra tentativa dentro de condições definidas, limites de tentativa e um orçamento de tempo Um erro permanente não se torna bem-sucedido, e a retentativa não substitui a consulta de estado
Reconciliação Comparação entre intenção da solicitação, resultado de negócio, registros de transação ou rodada e efeito no livro-razão Ela não decide automaticamente todas as compensações
Escalonamento manual Uma pessoa autorizada investiga e decide quando a automação não pode concluir com segurança O julgamento humano não compensa logs ou definições de protocolo ausentes

Métodos HTTP não decidem a semântica de negócio do projeto. A RFC 9110 define PUT, DELETE e métodos seguros como idempotentes e alerta os clientes para não repetirem automaticamente solicitações não idempotentes, a menos que sua semântica real seja conhecida como idempotente ou o cliente consiga estabelecer que a solicitação original não foi aplicada. As chamadas de plataforma exibidas na referência pública da API usam POST; portanto, não se pode inferir comportamento seguro de retentativa apenas a partir do método HTTP.

1. Identificadores estáveis: separe rastreamento de identidade de negócio

Um projeto confiável normalmente precisa de pelo menos duas classes de identificadores:

  • ID de rastreamento da solicitação: correlaciona uma tentativa de transporte com logs, uma resposta e material de diagnóstico.
  • ID de transação de negócio: identifica uma intenção de negócio e correlaciona transferências, movimentações de livro-razão, rodadas ou apostas.

A referência pública da API mostra reqTraceId e, em alguns fluxos de transação, campos como merchantTransactionId, transactionId, roundId e betId. Ela descreve merchantTransactionId como um identificador exclusivo de transação do operador que pode apoiar a reconciliação.

Esses campos fornecem indícios de rastreabilidade. Eles não estabelecem comportamentos não confirmados, como se toda operação é deduplicada, o escopo e período de retenção da deduplicação, o que acontece quando o mesmo ID chega com parâmetros diferentes ou se uma repetição devolve o resultado original. Essas semânticas exigem um protocolo formal e testes no ambiente aplicável.

O rascunho da IETF draft-ietf-httpapi-idempotency-key-header-07 propôs um cabeçalho Idempotency-Key. Em 9 de agosto de 2026, essa versão estava expirada e arquivada e não havia se tornado uma RFC. Ela pode ser tratada apenas como insumo histórico de projeto — não como padrão atual, protocolo da AG ou evidência de que a AG oferece suporte a esse cabeçalho.

2. Retentativas: faça tentativas limitadas apenas para operações e falhas seguras

Uma retentativa automática deve atender a ambas as condições: a falha é classificada como transitória, e a repetição é segura segundo o protocolo aplicável.

Cenário Princípio padrão Condição antes de uma retentativa automática
Consulta ou lista somente leitura Uma retentativa limitada pode ser considerada O protocolo confirma que não há efeito colateral e a falha é transitória
Criação de sessão Não recrie apenas por causa de um timeout Idempotência explícita ou consulta da sessão existente por seu identificador original
Mutação de carteira ou transferência Por padrão, verifique o estado ou reconcilie primeiro ID de negócio, escopo de idempotência e comportamento de resposta a duplicidade são confirmados
Processamento de callback O consumidor deve detectar eventos repetidos Ambas as partes concordam com o ID estável do evento ou transação usado para deduplicação
Erro de parâmetro, permissão ou assinatura Não repita automaticamente a mesma solicitação Corrija o parâmetro, acesso, relógio ou credencial e tome uma nova decisão
Timeout ou desconexão Marque o resultado como desconhecido Consulte primeiro pelo ID original; repita somente quando a semântica segura estiver estabelecida

As retentativas precisam de timeout por tentativa, número máximo de tentativas, orçamento total de tempo e condições de parada. Este artigo não prescreve valores numéricos: eles dependem da semântica da API, das restrições a montante, do risco de negócio e do acordo entre as partes.

3. Recuo exponencial com jitter: evite pressão sincronizada

Quando uma falha transitória pode ser repetida com segurança, um recuo exponencial limitado com jitter aleatório pode distribuir as tentativas ao longo do tempo. Em termos conceituais, o atraso aumenta a cada tentativa até um máximo, enquanto o jitter evita que muitos clientes façam uma retentativa no mesmo instante.

Tanto AWS quanto Google documentam o valor do recuo exponencial com jitter. O Google também deixa claro que a elegibilidade para retentativa depende de a falha poder ser repetida e de a operação ser idempotente. Um algoritmo de recuo não pode tornar segura uma operação não idempotente com efeito de escrita, nem substitui um orçamento geral de retentativa.

Evite estes antipadrões:

  • loops de retentativa imediatos ou sem limite;
  • uma política de retentativa para todo erro HTTP e de negócio;
  • retentativas nas camadas de gateway, SDK, serviço e fila que se multiplicam entre si;
  • gerar um novo ID de transação de negócio para cada tentativa, impedindo o reconhecimento da intenção original;
  • registrar chaves, credenciais completas ou dados sensíveis desnecessários durante retentativas;
  • continuar retentativas automatizadas indefinidamente após falhas repetidas.

A RFC 9110 também exige cautela com retentativas automatizadas; uma falha repetida não deve se transformar em repetição sem limite.

4. Estado desconhecido: não renomeie incerteza como falha

Quando uma solicitação deixou o chamador, mas nenhum resultado de negócio completo retorna, use um estado UNKNOWN separado. Um fluxo neutro em relação ao protocolo pode ser representado assim:

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

Em UNKNOWN, consulte resultados existentes, registros de transação ou movimentações de livro-razão pelo ID original da solicitação ou da transação de negócio. Se o protocolo não tiver um caminho de consulta autoritativo, interrompa ações automatizadas que possam duplicar efeitos, preserve o contexto e escale. Não presuma falha.

Os rótulos de estado, a API de consulta e os estados terminais devem seguir o protocolo das partes. Este diagrama é um método de projeto; ele não afirma que a AG implemente esses estados exatos.

5. Reconciliação: use vários registros para estabelecer o efeito final

Reconciliação é mais do que comparar dois valores de saldo. Para fluxos de carteira, aposta ou ganho, correlacione no mínimo:

  • a intenção de negócio original e o ID de rastreamento da solicitação;
  • o ID de transação de negócio do operador ou da plataforma;
  • os identificadores de transação, rodada e aposta da contraparte;
  • valor, moeda, direção e interpretação de tempo;
  • resultado de negócio da API e registros subsequentes;
  • movimentação do livro-razão, saldo atual e estado final de processamento.

Resultados úteis incluem reconciliado, falha confirmada, duplicidade, divergência de valor ou moeda, registro ausente e estado desconhecido. Cada divergência precisa de um responsável predefinido, conjunto de evidências, autoridade de compensação e condição de encerramento. Não reenvie a mutação financeira original como substituto da reconciliação.

Frequência, retenção e tolerância dependem do risco de negócio, volume, modelo de carteira e contrato. Este artigo não estabelece períodos ou limites fixos da AG.

6. Quando o escalonamento manual é obrigatório

Interrompa a automação e abra uma revisão manual auditável quando qualquer uma destas situações se aplicar:

  • o orçamento de retentativa limitada se esgotou e o estado de negócio continua desconhecido;
  • um ID de negócio aparece com valores, moedas, contas ou outros parâmetros críticos diferentes;
  • o resultado da solicitação, o registro da transação e a movimentação no livro-razão entram em conflito;
  • o registro autoritativo definido pelo protocolo não pode ser encontrado ou logs críticos estão incompletos;
  • há suspeita de débito duplicado, pagamento duplicado, acesso não autorizado ou incidente de segurança;
  • a compensação automatizada pode aumentar o impacto financeiro, de conformidade ou para o cliente.

O registro deve incluir IDs originais, uma linha do tempo, ações já executadas, evidências, avaliação de risco, aprovador e resultado final de encerramento. Segredos e credenciais não pertencem ao corpo de tickets.

Lista de verificação de implementação em uma página

  • Defina IDs estáveis separadamente para rastreamento de solicitações e transações de negócio.
  • Especifique escopo de idempotência, comportamento em conflitos e semântica de respostas repetidas para toda operação com efeitos colaterais.
  • Separe erros transitórios, erros permanentes e estados desconhecidos.
  • Faça retentativa automática somente quando a repetição for comprovadamente segura.
  • Defina timeouts, orçamento total, um teto de recuo exponencial limitado e jitter para caminhos elegíveis.
  • Evite que retentativas em várias camadas do sistema se multipliquem de forma inesperada.
  • Forneça consulta ou reconciliação pelo ID original para estados desconhecidos.
  • Reconcilie evidências de transação, rodada, valor, moeda e livro-razão.
  • Defina condições de parada da automação e responsabilidade pelo escalonamento manual.
  • Teste, em ambiente de homologação, casos de timeout, resposta perdida, envio duplicado e divergência de registros.

O que pode ser avaliado atualmente neste site

  • A referência pública da API mostra identificadores para solicitações e algumas transações de negócio, rodadas e apostas.
  • As notas de interface exigem avaliar o resultado de negócio no corpo da resposta, e não apenas o status HTTP.
  • Consultas de carteira, transação, rodada e aposta podem orientar o projeto de testes de rastreabilidade e reconciliação.
  • As páginas atuais descrevem carteiras única e de transferência, mas o projeto de confiabilidade deve seguir o modelo de carteira selecionado e o protocolo formal.

Limites a considerar

  • Esta página não afirma que todos os endpoints POST da AG sejam idempotentes nem que a AG ofereça suporte ao cabeçalho Idempotency-Key.
  • Ela não inventa escopo de deduplicação, retenção, respostas de conflito, contagens de retentativa, parâmetros de recuo nem cronogramas de reconciliação da AG.
  • Ela não acrescenta endpoint de consulta, compensação, estado ou produção.
  • Ela não promete zero duplicidades, zero perdas, consistência absoluta, segurança absoluta, desempenho fixo ou SLA.
  • Exemplos públicos de API não são um protocolo de produção, garantia de execução nem registro de admissão em produção para um projeto.

FAQ

Uma solicitação POST com falha pode receber retentativa automática?

Não com base apenas em “falhou” ou em POST. Primeiro, estabeleça se a falha é transitória, se a solicitação original talvez já tenha produzido efeito e se o protocolo formal fornece idempotência ou consulta pelo ID original. Caso contrário, a operação pertence ao tratamento de estado desconhecido e à reconciliação.

Um timeout significa que a transação falhou?

Não. Um timeout diz apenas que o chamador não recebeu um resultado completo a tempo. O servidor pode não ter começado, ainda estar processando ou ter obtido sucesso ou falhado. Consulte ou reconcilie usando o ID de negócio original.

Um ID de transação exclusivo comprova idempotência?

Não. Ele é uma base importante para reconhecer uma intenção de negócio, mas o protocolo também deve definir como o serviço o armazena e compara, seu escopo e tempo de vida, conflitos de parâmetros e o resultado retornado em uma repetição.

Uma retentativa deve receber um novo ID de solicitação?

Isso depende de como o protocolo separa uma intenção de negócio de uma tentativa de transporte. Em geral, o ID de transação de negócio precisa permanecer estável. Se um ID de rastreamento é reutilizado ou derivado deve estar explícito no contrato de interface, e não ser inferido deste artigo ou de um nome de campo.

Leituras relacionadas e próximos passos

Para projetar a confiabilidade de uma integração específica, use a seção “Fale conosco” para informar o modelo de carteira, a direção da chamada, as operações de negócio críticas e as atuais capacidades de reconciliação. A AG poderá então confirmar identificadores, semântica de consulta, limites de retentativa e responsabilidade de escalonamento conforme o protocolo formal, sem prometer antecipadamente comportamento em produção.

Fontes e escopo

Campos relevantes e o escopo da página aparecem na referência pública da API, na visão geral da Slots API e no processo de integração. A implementação ainda deve seguir o protocolo e o comportamento observado no ambiente acordado entre ambas as partes.

Fontes gerais de confiabilidade:

Estas fontes explicam padrões gerais. Elas não confirmam que a AG use algoritmo, parâmetros ou cabeçalho de qualquer fornecedor. Os responsáveis por API, carteira, SRE, segurança e reconciliação devem revisar a semântica do projeto e os campos de exemplo.

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