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

1. Pre-Auth-Rate-Limit pro IP

Bevor der Authorization-Header gelesen wird, begrenzt ein Limiter den Traffic pro Quell-IP. Der Standard beträgt 120 Anfragen pro Minute pro IP. Diese Ebene schützt vor volumetrischen Angriffen und Credential Stuffing.

Eine Überschreitung liefert 429 RATE_LIMITED mit Retry-After: 60. Kein Schlüssel wird geprüft, kein Credit wird verbraucht.

2. Token Bucket pro Schlüssel

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

Plan	Kapazität (Tokens)	Nachfüllrate
Free	10	10 Tokens/Min
Starter	60	60 Tokens/Min
Pro	500	500 Tokens/Min
Business	1.000	1.000 Tokens/Min
Enterprise	1.200	1.200 Tokens/Min

Jede authentifizierte Anfrage verbraucht einen Token. Der Bucket wird kontinuierlich aufgefüllt (gebrochene Nachfüllung), du musst also keinen vollen Minutentick abwarten, bevor du es erneut versuchen kannst.

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 öffentliche Antwort setzt diese Header:

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

RateLimit-Policy: IETF-Draft-Format, beschreibt die Policy. q ist die Bucket-Kapazität, w das Fenster in Sekunden.
X-RateLimit-Limit: Bucket-Kapazität, identisch mit q oben.

X-RateLimit-Remaining wird nicht bei jeder Anfrage ausgegeben: er wird ausschließlich bei einer 429-Ablehnung auf 0 gesetzt (die PL/pgSQL-Funktion, die einen Token konsumiert, liefert die verbleibende Tokenzahl nicht zurück, und ein zusätzlicher Read hätte unnötige Latenzkosten). Dimensioniere deinen Client anhand der Kapazität, des Retry-After-Headers und deiner eigenen clientseitigen Messungen, nicht anhand eines Echtzeit-Serverzählers.

Bei einem 429 hast du zusätzlich:

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

Der Client muss Retry-After respektieren und mindestens die angegebenen Sekunden warten, bevor er es erneut versucht.

Empfohlene Retry-Strategie

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

Zähle die Tokens clientseitig anhand von X-RateLimit-Limit. Führe deinen eigenen lokalen Bucket, um Sättigung vor dem Senden zu antizipieren.
Bei 429 RATE_LIMITED lies Retry-After. Warte mindestens diese Dauer.
Bei aufeinanderfolgenden 429-Antworten wende einen Multiplikator an: 2x, 4x, 8x mit einem Deckel bei 60 Sekunden.
Füge einen zufälligen Jitter von plus/minus 20 % hinzu, damit mehrere Clients nicht synchron retryen.
Begrenze die Gesamtanzahl der Retries (z. B. 5). Darüber logge als Fehler und mach es im Monitoring sichtbar.

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: repliziere den Server-Bucket lokal und starte eine Anfrage nur bei verfügbarem Token. Das vermeidet 429-Antworten und Jitter.
Parallelität nach Kapazität: ein Pro-Plan hat 500 Tokens/Min, also rund 8 Anfragen pro Sekunde. Acht parallele Worker sind effizienter als ein einzelner Worker, der 500 Iterationen pro Minute mit Sleeps macht.
Aufteilung teurer Endpunkte: bei 500 page-crawl-check (10 Credits) und 500 dmarc/lookup (1 Credit) teile sie in zwei getrennte Queues, um den Credit-Verbrauch zu glätten und das Rate Limit leichter einzuhalten.
Wartungsfenster: manche Batches können außerhalb der Hauptzeiten laufen, um nicht mit dem Echtzeit-Traffic um das Kontingent zu konkurrieren.

Was als Anfrage zählt

Jede authentifizierte HTTP-Anfrage zählt für einen Token, auch wenn sie mit 400 oder 500 fehlschlägt. Das Rate Limit schützt das Backend; Input-Validierung erfolgt erst, nachdem ein Token erhalten wurde.

Ausnahmen:

429 RATE_LIMITED: verbraucht offensichtlich keinen Token, da der Bucket leer ist.
401 INVALID_API_KEY: berührt den Bucket pro Schlüssel nicht (welcher Schlüssel das ist, weiß man noch nicht). Das Rate Limit pro IP zählt hingegen.
403 IP_NOT_ALLOWED: verbraucht weder Token noch Credit, da die Prüfung vor dem Verbrauch erfolgt.

Kapazität erhöhen

Die Kapazität des Token Buckets ist eine Eigenschaft des Plans, kein Parameter des Schlüssels. Zum Erhöhen:

Wechsle über das CaptainDNS-Dashboard zu einem höheren Plan.
Die Wirkung ist sofort: der Schlüssel erbt die neue Obergrenze ab der nächsten Anfrage.

Enterprise-Kunden können mit ihrem CaptainDNS Account Manager eine individuelle Obergrenze verhandeln (bis zu 5.000 req/min auf Anfrage).

Einen 429 diagnostizieren

Ein unerwarteter 429 kann mehrere Ursachen haben:

Pre-Auth-Bucket: du überschreitest 120 req/min von einer einzelnen IP. Prüfe, ob sich mehrere Dienste dieselbe Egress-IP teilen (NAT, CGNAT).
Token Bucket pro Schlüssel: dein Plan bietet nicht die nötige Kapazität. Upgrade oder weniger Parallelität.
Punktueller Spike: ein ungeglätteter Batch hat 200 Anfragen in einer Sekunde abgesetzt. Füge clientseitig Jitter und Glättung hinzu.
Zeitversatz: in seltenen Fällen, wenn dein Server nicht mit NTP synchron ist, kann der Retry-After-Header übertrieben wirken. Synchronisiere deine Uhr.

Falls das Problem trotz gewissenhafter Einhaltung von Retry-After bestehen bleibt, öffne ein Support-Ticket mit der X-Request-Id einer repräsentativen 429-Anfrage.