Suavizzare le chiamate con il rate limiting

La API pubblica CaptainDNS applica due livelli di rate limiting: uno per IP sorgente prima dell'autenticazione, è un token bucket per chiave la cui capacita dipende dal piano. Questa guida spiega entrambi i livelli è come scrivere un client rispettoso.

Due livelli di protezione

Rate limit per IP pre-auth

Prima di leggere l'header Authorization, un limitatore in memoria limita il traffico per IP sorgente. Il default sono 120 richieste al minuto per IP, regolabile lato CaptainDNS. Questo livello protegge da attacchi volumetrici è credential stuffing.

Un superamento restituisce 429 RATE_LIMITED con Retry-After: 60. Nessuna chiave viene verificata, nessun credito consumato.

Token bucket per chiave

Una volta autenticata la chiave, un token bucket persistente in Postgres gestisce il limite per chiave. La capacita è allineata al piano:

Ogni richiesta autenticata consuma un token. Il bucket si ricarica continuamente (ricarica frazionaria), quindi non devi aspettare un tick completo.

Un bucket vuoto restituisce 429 RATE_LIMITED. L'header Retry-After contiene i secondi fino al prossimo token disponibile.

Header di risposta

Ogni risposta include questi header standard:

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

In un 429, in più:

Retry-After: 12

Il client deve rispettare questo valore è attendere almeno i secondi indicati.

Strategia di retry raccomandata

Il pattern idiomatico è un backoff esponenziale limitato:

1. Dopo ogni risposta, leggi X-RateLimit-Remaining. Se il rapporto è sotto il 20 %, rallenta preventivamente.
2. Su 429 RATE_LIMITED, leggi Retry-After è attendi almeno quel tempo.
3. Se accumuli più 429 consecutivi, applica un moltiplicatore: 2x, 4x, 8x con un tetto a 60 secondi.
4. Aggiungi un jitter casuale di +/- 20 %.
5. Limita il numero totale di retry (es. 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

Strategie per pipeline batch

Le integrazioni che elaborano grandi volumi in batch traggono beneficio da strategie diverse:

• Token bucket lato client: replica localmente il bucket del server è invia solo se un token è disponibile.
• Parallelizzazione in base alla capacita: un piano Pro ha 500 token/min, circa 8 req/s. Otto worker in parallelo sono più efficienti di uno con sleep.
• Separazione di endpoint costosi: distribuisci chiamate costose è leggere in code distinte.
• Finestre di manutenzione: alcuni batch possono girare fuori dalle ore di punta.

Cosa conta come richiesta

Ogni richiesta HTTP autenticata consuma un token, anche se fallisce con 400 o 500. Eccezioni:

• 429 RATE_LIMITED non consuma token.
• 401 INVALID_API_KEY non tocca il bucket per chiave, ma conta nel rate limit per IP.
• 403 IP_NOT_ALLOWED non consuma ne token ne credito.

Aumentare la capacita

La capacita del token bucket è una proprieta del piano. Per aumentarla, passa a un piano superiore da /account/billing; l'effetto è immediato. I clienti Enterprise possono negoziare un tetto personalizzato fino a 5 000 req/min.

Diagnosticare un 429

Cause possibili:

• Bucket pre-auth: superi 120 req/min su un singolo IP. Verifica che più servizi non condividano lo stesso egress (NAT, CGNAT).
• Token bucket per chiave: il piano non offre la capacita necessaria.
• Picco episodico: un batch non suavizzato ha emesso 200 richieste in un secondo.
• Deriva di clock: rari casi di server senza NTP.

Strumenti CaptainDNS correlati

• Il DNS lookup permette di verificare manualmente un record senza consumare crediti.
• Il DMARC monitoring aggrega i report DMARC senza passare dalla API pubblica.

Prossimo passo: l'idempotenza per risparmiare crediti è token sui retry, o i codici d'errore.