Entwickler/Grundlagen

Gleichmäßiger Verkehr, kurze Spitzen erlaubt.

Die API begrenzt Anfragen mit Token-Buckets. Ein Bucket fasst eine Spitze, füllt sich gleichmäßig wieder auf und antwortet mit 429 rate_limit_exceeded, wenn er leer ist.

Die Buckets

Ein Bucket startet voll. Jede Anfrage nimmt einen Token, und die Tokens kommen mit der Rate aus der Tabelle zurück. Bei 1.200 pro Minute sind das 20 Anfragen pro Sekunde, und eine Spitze von bis zu 300 auf einmal ist in Ordnung.

Bucket	Gilt für	Auffüllung	Spitze
Pro IP-Adresse	Alle Anfragen einer Adresse außer den Check-ins unten, mit oder ohne Anmeldung. Nicht gezählt werden OPTIONS, /v1/health, /v1/readyz und /v1/password/forgot.	3.000 pro Minute	300
Pro API-Schlüssel	Jede authentifizierte Anfrage, gezählt je Schlüssel.	1.200 pro Minute	300
Pro Heartbeat-Slug und IP	Check-ins an /v1/heartbeat/{slug}. Diese Aufrufe brauchen keinen Schlüssel.	120 pro Minute	20

Ein API-Aufruf nimmt zuerst einen Token aus dem IP-Bucket und dann aus dem Schlüssel-Bucket und schlägt fehl, sobald einer leer ist. Wiederholungen mit gespeicherter Antwort zählen wie jede andere Anfrage. Anmeldung, Registrierung, Kontakt und die Formulare der öffentlichen Statusseiten haben eigene, engere Buckets pro IP-Adresse.

Header

Header	Wert
`X-RateLimit-Limit`	Die Auffüllrate des IP-Buckets in Anfragen pro Minute.
`X-RateLimit-Remaining`	Ganze Anfragen, die nach dieser noch im IP-Bucket übrig sind.
`X-RateLimit-Reset`	Ein Unix-Zeitstempel in Sekunden: der Moment, in dem der IP-Bucket wieder eine Anfrage aufgefüllt hat. Der Bucket füllt sich fortlaufend, der Wert liegt also ungefähr bei jetzt und nicht am Ende eines Fensters.
`Retry-After`	Nur bei 429: ganze Sekunden, die du warten sollst, mindestens 1.

Die X-RateLimit-*-Header beschreiben den IP-Bucket, nicht den Schlüssel-Bucket. Ein Schlüssel, der seine 300 Anfragen Spitze verbraucht hat, bekommt 429 und Retry-After: 1, während die Header noch einen gesunden IP-Bucket zeigen. Verlass dich auf 429 und Retry-After, nicht auf Remaining.

curl -si https://app.upfour.io/v1/monitors \
  -H "Authorization: Bearer $UP4_API_KEY" | grep -i -E '^(HTTP|x-ratelimit|retry-after)'

HTTP/2 429
retry-after: 1
x-ratelimit-limit: 3000
x-ratelimit-remaining: 299
x-ratelimit-reset: 1793102400

{ "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "request_id": "req_…" } }

Nach einem 429

Sende so viele Sekunden nichts, wie Retry-After nennt.
Wiederhole dieselbe Anfrage. Ein POST mit Idempotency-Key kannst du gefahrlos wiederholen.
Kommt wieder ein 429, warte jedes Mal länger und füge eine zufällige Verzögerung hinzu, damit parallele Worker nicht gleichzeitig neu starten.

Verteile große Mengen, statt sie durchzujagen: POST /monitors/batch und POST /monitors/bulk legen viele Monitore in einer Anfrage an oder ändern sie.

Wie gezählt wird

Läuft der gemeinsame Zähler-Speicher von up4, zählen alle API-Server zusammen. Ist er nicht erreichbar, zählt jeder Server für sich. Die Obergrenze, die du in so einer Phase erreichen kannst, kann dann höher liegen, ist aber nie unbegrenzt.

Typische Fehler

Bis X-RateLimit-Reset warten. Der Wert liegt fast bei jetzt; nutze Retry-After.
Remaining als Budget deines Schlüssels lesen. Es gehört zum IP-Bucket.
Viele Worker hinter einer Adresse und einem Schlüssel betreiben. Sie teilen sich beide Buckets.
Sofort in einer engen Schleife wiederholen. Jeder neue Versuch kostet ebenfalls einen Token.
Auf Statusänderungen pollen. Ein Webhook schickt sie dir.

War diese Seite hilfreich?