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 é um token bucket por chave cuja capacidade depende do plano. Este guia explica as duas camadas é como escrever um cliente que as respeita sem perder requisicoes.

Duas camadas de proteção

Limite por IP pre-auth

Antes de ler o header Authorization, um limitador em memoria limita o tráfego por IP de origem. O padrao é 120 requisicoes por minuto por IP, ajustavel no lado CaptainDNS. Esta camada protege contra ataques volumetricos é credential stuffing.

Um estouro retorna 429 RATE_LIMITED com Retry-After: 60. Nenhuma chave é verificada, nenhum credito 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 requisicao autenticada consome um token. O bucket se recarrega continuamente (recarga fracionaria), entao você não precisa esperar um tick completo de minuto.

Um bucket vazio retorna 429 RATE_LIMITED. O header Retry-After contem os segundos até o proximo token disponível.

Headers de resposta

Cada resposta inclui estes headers padrao:

RateLimit-Policy: "default";q=60;w=60
RateLimit: limit=60, remaining=58, reset=42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1717200000

Em um 429, adicionalmente:

Retry-After: 12

O cliente deve respeitar este valor é esperar pelo menos os segundos indicados.

Estrategia de retry recomendada

O padrao idiomatico é um backoff exponencial limitado:

1. Em cada resposta, leia X-RateLimit-Remaining. Se a razao estiver abaixo de 20 %, desacelere preventivamente.
2. Em 429 RATE_LIMITED, leia Retry-After é espere pelo menos esse tempo.
3. Se você acumular varios 429 consecutivos, aplique um multiplicador: 2x, 4x, 8x com teto de 60 segundos.
4. Adicione um jitter aleatorio 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

Estrategias para pipelines em batch

Integracoes que processam grandes volumes em batch beneficiam de estrategias adicionais:

• Token bucket no cliente: replique localmente o bucket do servidor é 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 sao mais eficientes que um unico com sleeps.
• Separacao de endpoints caros: distribua chamadas caras é baratas em filas distintas.
• Janelas de manutencao: alguns batches podem rodar fora do horario de pico.

O que conta como requisicao

Cada requisicao HTTP autenticada consome um token, mesmo se falhar com 400 ou 500. Excecoes:

• 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 credito.

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 possiveis:

• Bucket pre-auth: você ultrapassa 120 req/min em um unico IP. Verifique se varios servicos 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 suavizacao enviou 200 requisicoes 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 relatorios DMARC sem passar pela API pública.

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