Suavizar chamadas com rate limiting

A API pública CaptainDNS aplica duas camadas de rate limiting: uma por IP de origem antes da autenticação e um token bucket por chave cuja capacidade depende do plano. Este guia explica as duas camadas e como escrever um cliente que as respeita sem perder requisições.

Duas camadas de proteção

Limite por IP pre-auth

Antes de ler o header Authorization, um limitador em memória limita o tráfego por IP de origem. O padrão é 120 requisições por minuto por IP, ajustável no lado CaptainDNS. Esta camada protege contra ataques volumétricos e credential stuffing.

Um estouro retorna 429 RATE_LIMITED com Retry-After: 60. Nenhuma chave é verificada, nenhum crédito consumido.

Token bucket por chave

Uma vez autenticada a chave, um token bucket persistente no Postgres gerencia o limite. A capacidade segue o plano:

Cada requisição autenticada consome um token. O bucket se recarrega continuamente (recarga fracionária), então você não precisa esperar um tick completo de minuto.

Um bucket vazio retorna 429 RATE_LIMITED. O header Retry-After contém os segundos até o próximo token disponível.

Headers de resposta

Cada resposta pública posiciona estes headers:

RateLimit-Policy: "default";q=60;w=60
X-RateLimit-Limit: 60

• RateLimit-Policy: formato IETF draft, descreve a política. q é a capacidade do bucket, w a janela em segundos.
• X-RateLimit-Limit: capacidade do bucket, idêntica ao q acima.

X-RateLimit-Remaining não é emitido a cada requisição: é posicionado em 0 apenas em caso de recusa 429 (a função PL/pgSQL que consome um token não retorna o número de tokens restantes, e uma leitura adicional teria um custo de latência injustificado). Dimensione seu cliente com base na capacidade, no header Retry-After e em suas próprias medidas do lado cliente, não em um contador servidor em tempo real.

Em um 429, você terá adicionalmente:

Retry-After: 12
X-RateLimit-Remaining: 0

O cliente deve respeitar Retry-After e aguardar no mínimo o número de segundos indicado antes de tentar novamente.

Estratégia de retry recomendada

O padrão idiomático é um backoff exponencial limitado:

1. Conte os tokens no lado cliente a partir de X-RateLimit-Limit. Mantenha seu próprio bucket local para antecipar a saturação antes de enviar a requisição.
2. Em 429 RATE_LIMITED, leia Retry-After e espere pelo menos esse tempo.
3. Se você acumular vários 429 consecutivos, aplique um multiplicador: 2x, 4x, 8x com teto de 60 segundos.
4. Adicione um jitter aleatório de +/- 20 %.
5. Limite o total de retries (por exemplo 5).

delay = retryAfter + random(-0.2, 0.2) * retryAfter
for attempt in 1..5:
    response = send(request)
    if response.status != 429:
        return response
    retryAfter = response.header["Retry-After"] or delay * attempt
    sleep(min(retryAfter, 60))
raise RateLimitExceeded

Estratégias para pipelines em batch

Integrações que processam grandes volumes em batch se beneficiam de estratégias adicionais:

• Token bucket no cliente: replique localmente o bucket do servidor e envie apenas quando um token estiver disponível.
• Paralelismo baseado na capacidade: um plano Pro tem 500 tokens/min, cerca de 8 req/s. Oito workers em paralelo são mais eficientes que um único com sleeps.
• Separação de endpoints caros: distribua chamadas caras e baratas em filas distintas.
• Janelas de manutenção: alguns batches podem rodar fora do horário de pico.

O que conta como requisição

Cada requisição HTTP autenticada consome um token, mesmo se falhar com 400 ou 500. Exceções:

• 429 RATE_LIMITED não consome token.
• 401 INVALID_API_KEY não toca o bucket por chave, mas conta no limite por IP.
• 403 IP_NOT_ALLOWED não consome nem token nem crédito.

Aumentar a capacidade

A capacidade do token bucket é propriedade do plano. Para aumentar, passe a um plano superior em /account/billing; o efeito é imediato. Clientes Enterprise podem negociar um teto customizado até 5.000 req/min.

Diagnosticar um 429

Causas possíveis:

• Bucket pre-auth: você ultrapassa 120 req/min em um único IP. Verifique se vários serviços não compartilham o mesmo egress (NAT, CGNAT).
• Token bucket por chave: seu plano não oferece a capacidade necessária.
• Pico pontual: um batch sem suavização enviou 200 requisições em um segundo.
• Desvio de clock: casos raros de servidores sem NTP.

Ferramentas CaptainDNS relacionadas

• O DNS lookup permite verificar manualmente um registro sem gastar créditos.
• O DMARC monitoring agrega relatórios DMARC sem passar pela API pública.

Próximo passo: a idempotência para economizar créditos em retries, ou os códigos de erro.