Performance

Rate limit na API CPF: retry, backoff e fila

Como tratar 429 sem criar tempestade de tentativas, usando backoff, limites de fila e observabilidade.

Imagem editorial sobre Controle de taxa e tentativas
Controle de taxa e tentativas.

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

  1. Mantenha uma fila de consultas autorizadas.
  2. Limite a quantidade de workers concorrentes.
  3. Quando surgir 429, reduza a taxa de envio.
  4. Aguarde intervalos crescentes com pequena variação aleatória.
  5. 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.

Continue aprendendo