Tratamento de códigos HTTP 402 e 429 na lógica de nova tentativa de API

Tratamento de códigos HTTP 402 e 429 na lógica de nova tentativa de API.

Entendendo a arquitetura de status HTTP no CPaaS pré-pago

Ao construir integrações de comunicação automatizadas, seu software depende de respostas HTTP previsíveis para manter o tempo de atividade. Ao contrário do software pós-pago padrão, onde os limites são elásticos, um CPaaS pré-pago de marca branca opera em um modelo estrito de saldo de livro-razão e financiamento em tempo real. Cada solicitação de API aciona verificações imediatas de autorização em relação ao saldo da sua carteira ativa para garantir fundos.

Anatomia do erro HTTP 402 Payment Required

Um código de status HTTP 402 indica que a operação falhou porque o saldo da sua conta está esgotado ou incapaz de cobrir os custos estimados. Por exemplo, o provisionamento de um número de telefone requer fundos suficientes para a alocação inicial, alinhando-se ao nosso fluxo de trabalho de reserva pré-paga. Se o seu saldo cair abaixo do limite pré-pago de USD 20, o gateway rejeita imediatamente as cargas úteis com um erro 402. Tratar isso como uma falha de rede transitória é inadequado.

Anatomia do erro HTTP 429 Too Many Requests

Em contraste, uma resposta HTTP 429 sinaliza um evento de limitação de taxa acionado pelo excesso de limites de throughput, como o envio de muitas solicitações Verify OK por segundo. Enquanto o erro 402 denota um bloqueio financeiro, o erro 429 é puramente operacional e temporário. Quando seu sistema encontra um status 429, os cabeçalhos de resposta geralmente incluem uma diretiva Retry-After indicando quantos segundos seu worker deve aguardar antes do próximo envio.

Projetando políticas inteligentes de nova tentativa e disjuntores

Escrever código de cliente resiliente requer separar o gerenciamento de erros em ramos distintos com base no código de status. Para HTTP 429, implemente um loop de nova tentativa com backoff randomizado e limites rígidos. Para HTTP 402, acione um disjuntor que pause o tráfego de saída, inicie uma recarga automática de saldo ou alerte um administrador, aguardando a confirmação via webhook de que os fundos foram liberados para uso contínuo.

Integrando verificações de saldo com limitação de taxa

Para otimizar o desempenho do sistema, combine verificações pré-voo do saldo do livro-razão com o gerenciamento inteligente de filas. Antes de enviar campanhas em massa de SMS ou processar listas de destino E.164, consulte seu endpoint de saldo para garantir que você ultrapasse o limite operacional mínimo. A classificação adequada de erros também se conecta diretamente à saúde geral da plataforma e à segurança das transações do sistema.

Material relacionado: limites de taxa API do piloto à produção · idempotência, retries e dinheiro · Pico de abuso: interrupção sem falso sucesso.

Comece com a IOSOR para infraestrutura CPaaS confiável

Bifurque o cliente: HTTP 402 significa que o hold pré-pago falhou ou a carteira não consegue liquidar — pare a intenção, mostre o carregamento, não reenvie. HTTP 429 significa que a janela de ritmo está cheia — honre Retry-After e reenvie a mesma Idempotency-Key. Um tratador que reenvia ambos os códigos cunhará uma segunda tempestade de débitos.

Conclusão IOSOR

402 é uma paragem de dinheiro; 429 é uma pausa de ritmo. Não são o mesmo reenvio.

Faça: pare no 402 até um hold novo poder liquidar; recue 429 com a chave original para o prepaid ver uma intenção.

Não faça: tratar 402 como um 429 mole, nem martelar qualquer código até 200 enquanto o ledger ainda decide.