IOSOR

IOSOR Guias

Idempotência da API de envio: duplicados, retries e dinheiro

Guia para desenvolvedores de APIs prepaid de envio — chaves de idempotência, retries seguros, prevenção de duplicados e correlação amigável ao ledger, para erros de engenharia não virarem incidentes financeiros.

Timeouts acontecem. Balanceadores fazem retry. Clientes móveis dão double-tap. Sem idempotência, um produto de "enviar uma vez" vira débito prepaid em dobro e UX de OTP duplicado. Este guia é para engineering e product técnico que integram uma API de messaging prepaid white-label — onde cada duplicado aparece na carteira. IOSOR espera integrações money-aware: chamadas autenticadas, débitos correlacionáveis e erros de cliente que nunca despejam payloads de marcas alheias. Perto de USD 1.000+ de uso mensal da plataforma, a disciplina de duplicados deixa de ser opcional.

Por que duplicados viram problemas de dinheiro

Modo de falha O usuário vê A carteira vê
Timeout de cliente + retry cego Dois OTPs / dois alertas Dois débitos
Handler de webhook não idempotente Efeitos colaterais duplos Confusão no sucesso
Reenvio do usuário empilhado no auto-retry Usuários irritados Unidades acumuladas
Sem correlação Tickets de "falhou" Linhas de ledger sem pareamento

Demos perdoam isso. Finanças de produção não.

Chaves de idempotência que sobrevivem a retries

Um caminho de envio sério aceita uma chave gerada pelo cliente que é única por intenção de negócio, não por tentativa TCP. Ela deve devolver o mesmo resultado aceito no replay dentro de uma janela TTL clara. Isso evita criar em silêncio um segundo débito para a mesma intenção. A chave deve ser registrada ao lado do ID da mensagem e da referência prepaid. Ela deve funcionar através de timeouts, retries de gateway e redrives de suporte.

Orçamentos de retry vs reenvio do usuário

Retries automáticos precisam de um orçamento: tentativas máximas, backoff e quais classes de erro são passíveis de retry. O reenvio iniciado pelo usuário é uma ação de produto diferente com seus próprios limites e custos. Misturar ambos transforma uma rede instável em um evento financeiro. Combine tudo com parada por saldo baixo e motivos de rejeição claros para que produto e finanças compartilhem uma única verdade.

Checklist de comprador / engineering

  1. Semântica de chave de idempotência e TTL documentados.
  2. Teste de replay que prova um débito por intenção.
  3. Orçamento de retry automático separado da lógica de reenvio do usuário.
  4. IDs de correlação entre requisição, status da mensagem e ledger prepaid.
  5. Staging que exercita corredores reais — luzes verdes simuladas não são lançamentos.
  6. Higiene de chaves e privilégio mínimo para credenciais de envio.
  7. Tratamento de códigos 429 e 503 sem perder a chave de intenção original.
  8. Alertas automatizados para altas taxas de rejeição de chaves duplicadas.

Sinais de alerta

  • "Apenas tente novamente até 200" sem usar chaves de idempotência.
  • Handlers de webhook que não são idempotentes e disparam efeitos colaterais duas vezes.
  • Chaves secretas ou tokens de auth aparecendo em logs ou tickets de suporte.
  • Erros que exibem payloads de marcas alheias ou stack traces internos aos usuários.
  • Falta de monitoramento para rejeições de chaves.

Comece com IOSOR

Na consola de envio, dispare um OTP ou alerta com uma chave de idempotência gerada pelo cliente. Force um timeout de cliente e volte a enviar o mesmo pedido dentro do TTL da chave. Abra o ledger prepaid: essa intenção deve mostrar um débito e uma mensagem visível. Duas linhas significam que a chave não sobreviveu ao retry — corrija TTL e handler antes de deixar o corredor em Live.

Conclusão IOSOR

Faça: trate cada envio como evento de ledger primeiro. A chave é única por intenção de negócio, não por tentativa TCP.

Este guia foi útil?

Guias relacionados