Entenda o erro 429 na API CPF
O status 429 Too Many Requests significa que uma aplicação excedeu o ritmo permitido pelo serviço. A documentação menciona limites por minuto ou por dia. Seu plano e configuração determinam o comportamento aplicável: não presuma um número fixo apenas porque viu um exemplo na internet.
Se dez trabalhadores repetirem a mesma consulta simultaneamente após 429, o problema pode piorar. Uma implementação de retry com backoff deve limitar a concorrência e o número de tentativas.
Estratégia segura de retries
- Mantenha uma fila de consultas autorizadas.
- Limite a quantidade de workers concorrentes.
- Quando surgir 429, reduza a taxa de envio.
- Aguarde intervalos crescentes com pequena variação aleatória.
- Defina número máximo de tentativas e estado final de falha.
Se o provedor fornecer Retry-After, avalie seu valor, mas não dependa da existência do cabeçalho. Não repita 401, 402 ou 400 automaticamente: são causas que pedem correção de credencial, saldo ou dado de entrada.
Exemplo de cálculo de espera com jitter
import random
def espera_antes_de_tentar(n_tentativa: int) -> float:
base = min(0.5 * (2 ** n_tentativa), 8.0)
return base + random.uniform(0, 0.3)
# Intervalos aproximados em segundos, sem requests reais.
for tentativa in range(3):
print(round(espera_antes_de_tentar(tentativa), 2))
Esse cálculo não autoriza novas consultas por si só. É um exemplo de espera a ser combinado com fila, resposta HTTP, política de créditos e regras de negócio. Para um sistema que cobra consulta, um timeout pode ter ocorrido depois do processamento: não suponha que repetir não gerará novo consumo.
Rate limit também no seu backend
Mesmo que o provedor possua limites, imponha controles próprios por usuário, conta ou função, evitando uso abusivo. O endpoint de consulta contém CPF em query string, então evite gravá-lo em relatórios de tráfego. Para depurar, use somente métricas agregadas por status e identificadores internos.
Perguntas frequentes
429 é problema de API Key inválida?
Não. API Key ausente ou inválida corresponde ao erro 401 documentado.
Posso aumentar o número de tentativas até funcionar?
Não é boa prática. Isso aumenta carga, risco de consumo de créditos e complexidade do suporte. Prefira contenção, limite máximo e alerta.
