# Ratenlimits

> Die Ratenlimits der up4-API: die drei Buckets, was X-RateLimit und Retry-After tatsächlich melden und wie du nach einem 429 wartest.

Source: https://upfour.io/de/docs/api/rate-limits

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](https://upfour.io/docs/api/errors#code-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`.

```bash
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

1. Sende so viele Sekunden nichts, wie `Retry-After` nennt.
2. Wiederhole dieselbe Anfrage. Ein `POST` mit `Idempotency-Key` kannst du gefahrlos wiederholen.
3. 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](https://upfour.io/docs/api/webhooks.md) schickt sie dir.