Tratando erros, novas tentativas e idempotência na API

Projete para a falha, não apenas para o caminho feliz. O caso mais perigoso é o ambíguo: uma requisição que pode ou não ter tido sucesso antes de a conexão cair.

Use uma chave de idempotência nas requisições de pedido, de forma que uma nova tentativa segura após um timeout retorne o pedido existente em vez de criar uma cobrança duplicada. Repita erros transitórios (limites de taxa, 5xx temporários) com backoff crescente e um teto.

Falhe rápido em erros permanentes, como uma requisição inválida ou saldo insuficiente, e leve-os a uma pessoa. Repetir essas tentativas só desperdiça tempo. Registre cada requisição e resposta com o ID do pedido para conseguir reconciliar depois.