Anfragen mit Rate Limiting glätten

Die CaptainDNS Public API setzt zwei Rate-Limit-Ebenen ein: eine pro Quell-IP vor der Authentifizierung und einen Token Bucket pro Schlüssel mit plan-abhängiger Kapazität. Dieses Handbuch erklärt beide Ebenen und wie man einen respektvollen Client schreibt.

Zwei Schutzebenen

Pre-Auth-Limit pro IP

Bevor der Authorization-Header ausgewertet wird, begrenzt ein In-Memory-Limiter den Traffic pro Quell-IP. Der Standard beträgt 120 Anfragen pro Minute pro IP. Eine Überschreitung liefert 429 RATE_LIMITED mit Retry-After: 60. Kein Schlüssel wird geprüft, kein Credit wird verbraucht.

Token Bucket pro Schlüssel

Sobald der Schlüssel authentifiziert ist, steuert ein in Postgres persistierter Token Bucket die Grenze. Die Kapazität ist an den Plan des Schlüssels gekoppelt:

Jede authentifizierte Anfrage verbraucht einen Token. Der Bucket wird kontinuierlich aufgefüllt (gebrochene Nachfüllung), Sie müssen also keinen vollen Minutentick abwarten.

Ein leerer Bucket liefert 429 RATE_LIMITED. Der Retry-After-Header gibt die Sekunden bis zum nächsten verfügbaren Token an.

Antwort-Header

Jede Antwort enthält folgende Standardheader:

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

Bei einem 429 zusätzlich:

Retry-After: 12

Der Client muss diesen Wert respektieren und mindestens die angegebenen Sekunden warten.

Empfohlene Retry-Strategie

Die idiomatische Vorgehensweise für einen respektvollen Client ist ein beschränkter exponentieller Backoff:

1. Nach jeder Antwort X-RateLimit-Remaining lesen. Fällt das Verhältnis unter 20 %, präventiv verlangsamen.
2. Bei 429 RATE_LIMITED den Retry-After-Header lesen und mindestens so lange warten.
3. Bei aufeinanderfolgenden 429-Antworten einen Multiplikator anwenden: 2x, 4x, 8x mit einem Deckel bei 60 Sekunden.
4. Einen zufälligen Jitter von plus/minus 20 % einbauen, damit mehrere Clients nicht synchron retryen.
5. Die Gesamtanzahl der Retries begrenzen (z. B. 5). Darüber als Fehler loggen und im Monitoring sichtbar machen.

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

Strategien für Batch-Pipelines

Integrationen, die große Mengen im Batch verarbeiten (z. B. ein nächtlicher Scan von 10.000 Domains), profitieren von zusätzlichen Strategien:

• Clientseitiger Token Bucket: Replizieren Sie den Server-Bucket lokal und senden Sie nur bei verfügbarem Token, um 429-Antworten komplett zu vermeiden.
• Parallelität nach Kapazität: Ein Pro-Plan hat 500 Tokens pro Minute, also rund 8 req/s. Acht parallele Worker sind effizienter als ein einzelner Worker mit Sleeps.
• Aufteilung teurer Endpunkte: Bei 500 page-crawl-check (10 Credits) und 500 dmarc/lookup (1 Credit) empfiehlt sich eine Aufteilung in zwei Warteschlangen.
• Wartungsfenster: Manche Batches können außerhalb der Hauptzeiten laufen.

Was als Anfrage zählt

Jede authentifizierte HTTP-Anfrage verbraucht einen Token, auch wenn sie mit 400 oder 500 fehlschlägt. Ausnahmen:

• 429 RATE_LIMITED verbraucht keinen Token.
• 401 INVALID_API_KEY berührt den Bucket pro Schlüssel nicht, zählt aber für das Limit pro IP.
• 403 IP_NOT_ALLOWED verbraucht weder Token noch Credit.

Kapazität erhöhen

Die Token-Bucket-Kapazität ist eine Plan-Eigenschaft. Zum Erhöhen wechseln Sie über /account/billing auf einen höheren Plan. Der Effekt ist sofort sichtbar. Enterprise-Kunden können mit ihrem Account Manager eine individuelle Obergrenze bis zu 5.000 req/min verhandeln.

Einen 429 diagnostizieren

Mögliche Ursachen:

• Pre-Auth-Bucket: mehr als 120 req/min von einer einzelnen IP. Prüfen Sie, ob mehrere Dienste sich dieselbe Egress-IP teilen (NAT, CGNAT).
• Token Bucket pro Schlüssel: der Plan bietet nicht genug Kapazität. Upgrade oder weniger Parallelität.
• Spontaner Spike: ein ungeglätteter Batch hat 200 Anfragen in einer Sekunde abgesetzt.
• Zeitversatz: seltene Fälle, in denen Ihr Server ohne NTP läuft.

Verwandte CaptainDNS-Tools

• DNS Lookup für manuelle Prüfungen ohne Credits.
• DMARC Monitoring für DMARC-Berichte außerhalb der Public API.

Weiter geht es mit der Idempotenz, um Credits und Tokens bei Retries zu sparen, oder mit den Fehlercodes.