API-Ratenlimits
Jede Anfrage an https://api.primecal.eu/api ist ratenlimitiert. Die Limits hängen davon ab,
wer aufruft (deine Stufe) und was du aufrufst (die Endpunkt-Kategorie).
Stufen
| Stufe | Wer sie erhält |
|---|---|
guest | Nicht authentifizierte Anfragen |
user | Angemeldete Benutzer und die meisten API-Schlüssel |
premium | Systemadministratoren und Benutzer im Enterprise- oder Store-Nutzungsplan |
Deine Stufe wird automatisch aus deinem Auth-Kontext aufgelöst — es gibt nichts zu konfigurieren. Ein API-Schlüssel kann auch seine eigene Stufe tragen, unabhängig vom Plan des aufrufenden Benutzers.
Kategorien und Limits
Jeder Endpunkt fällt basierend auf seinem Pfad in eine Kategorie. Limits sind Anfragen pro 60-Sekunden-Fenster, sofern nicht anders vermerkt.
| Kategorie | Trifft zu auf | guest | user | premium |
|---|---|---|---|---|
auth | /auth/* (ohne die unten genannten Pfade) | 8 | 20 | 40 |
oauth | /auth/google, /auth/microsoft | 60 | 120 | 240 |
availability | /auth/username-availability, /auth/email-availability, jeder /availability-Pfad | 30 | 80 | 180 |
booking | /reservations/*, /booking/*, /public-booking/* | 20 | 120 | 300 |
admin | /admin/* | 4 | 30 | 120 |
default | alles andere | 40 | 180 | 450 |
availability verwendet einen Token-Bucket-Algorithmus (erlaubt kurze Bursts); jede andere
Kategorie verwendet ein Sliding Window.
Das effektive Limit einer Anfrage kann automatisch reduziert werden, wenn PrimeCals Missbrauchspräventionssystem einen hohen Risikowert für deine IP/Identität feststellt. Die obige Tabelle ist der Basiswert, keine feste Garantie zu jedem Zeitpunkt.
Antwort-Header
Jede Antwort — erfolgreich oder nicht — enthält:
| Header | Bedeutung |
|---|---|
X-RateLimit-Limit | Dein Limit für die Kategorie und Stufe dieser Anfrage |
X-RateLimit-Remaining | Verbleibende Anfragen im aktuellen Fenster |
X-RateLimit-Reset | Unix-Zeitstempel (Sekunden), wann das Fenster zurückgesetzt wird |
X-RateLimit-Policy | <Algorithmus>;w=<FensterSekunden>;tier=<Stufe>;category=<Kategorie> |
Wenn du ratenlimitiert wirst
Eine Anfrage über dem Limit gibt HTTP 429 mit einem Retry-After-Header (Sekunden) und
einem JSON-Body zurück:
{
"statusCode": 429,
"message": "Too many requests",
"details": {
"tier": "user",
"category": "default",
"retryAfterSeconds": 12
}
}
Warte mindestens retryAfterSeconds, bevor du es erneut versuchst. Versuche es nicht in einer
engen Schleife erneut — das hält dich innerhalb desselben Fensters.
Praktische Hinweise
- Bündle und cache, wo möglich, besonders bei der
admin-Kategorie — ihre Limits sind absichtlich niedrig. - Authentifiziere dich — die
guest-Stufe ist über alle Kategorien hinweg am restriktivsten. Anmelden oder ein API-Schlüssel verdoppelt dein Budget in den meisten Kategorien ungefähr. - Ein 429 bedeutet nicht, dass etwas kaputt ist — es bedeutet, dass du schneller aufrufst,
als deine Stufe erlaubt. Prüfe
X-RateLimit-Remaining, bevor du null erreichst, statt erst nach einem 429 zu reagieren. - Wenn deine Integration wirklich ein höheres Limit braucht, erhalten höhere Nutzungspläne
(Enterprise, Store) automatisch die
premium-Stufe — siehe Pläne und Preise.