Ratenbegrenzungen
Die VaultPAM-API erzwingt Ratenbegrenzungen pro Client, um die Dienststabilität zu schützen. Alle API-Antworten enthalten x-ratelimit-*-Header, damit Ihr Client seinen aktuellen Verbrauch verfolgen und sich kontrolliert zurücknehmen kann, bevor ein Limit erreicht wird.
Antwort-Header
Jede API-Antwort enthält die folgenden Header:
| Header | Typ | Beschreibung |
|---|---|---|
x-ratelimit-limit | Ganzzahl | Maximal zulässige Anfragen im aktuellen Zeitfenster |
x-ratelimit-remaining | Ganzzahl | Verbleibende Anfragen im aktuellen Zeitfenster |
x-ratelimit-reset | Unix-Zeitstempel (Sekunden) | Zeitpunkt, zu dem das aktuelle Zeitfenster zurückgesetzt wird |
Bei einer Antwort 429 Too Many Requests wird ein zusätzlicher Header mitgesendet:
| Header | Typ | Beschreibung |
|---|---|---|
retry-after | Ganzzahl (Sekunden) | Mindestwartezeit vor einem erneuten Versuch |
Alle Header verwenden Namen in Kleinbuchstaben.
Ratenbegrenzungskategorien
Die API wendet je nach Vorgangstyp und aufrufendem Kontext unterschiedliche Limits an. Die x-ratelimit-*-Header in jeder Antwort spiegeln die für diese konkrete Anfrage geltende Limitkategorie wider.
Referenzwerte (nur als Orientierung — die x-ratelimit-*-Header sind maßgeblich):
| Kategorie | Limit |
|---|---|
| Anmeldeversuche pro IP | 60 pro Minute |
| API-Anfragen pro IP | 300 pro Minute |
| API-Anfragen pro authentifiziertem Benutzer | 120 pro Minute |
| Sensible Vorgänge pro Benutzer | 30 pro Minute |
Die oben gezeigten Limits dokumentieren die aktuellen Standardwerte. Verwenden Sie die Werte x-ratelimit-limit und x-ratelimit-remaining in jeder Antwort, um Entscheidungen über erneute Versuche zu treffen — die veröffentlichten Zahlen können sich ohne Vorankündigung ändern.
Umgang mit 429-Antworten
Wenn Sie eine Antwort 429 Too Many Requests erhalten:
- Lesen Sie den Wert des Headers
retry-after(Sekunden). - Pausieren Sie Ihre Anfrageschleife für mindestens diese Dauer.
- Wiederholen Sie die Anfrage.
Beispielantwort:
HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 120
x-ratelimit-remaining: 0
x-ratelimit-reset: 1747483200
retry-after: 37
Content-Type: application/json
{
"error": "RATE_LIMITED",
"message": "Too many requests. Retry after 37 seconds."
}
Empfohlene Client-Muster
Verbleibendes Budget vor Massenvorgängen prüfen
Lesen Sie x-ratelimit-remaining nach jeder Antwort. Fällt der Wert unter einen Schwellenwert (zum Beispiel 10), fügen Sie vor der nächsten Anfrage eine Pause ein, um ein 429 zu vermeiden.
Exponentielles Backoff für vorübergehende 429-Antworten
Wenn retry-after nicht vorhanden ist oder Sie mehrere aufeinanderfolgende 429-Antworten erhalten, verwenden Sie exponentielles Backoff mit Jitter:
wait = min(base * 2^attempt + random_jitter, max_wait)
x-ratelimit-reset zur Fehlersuche protokollieren
Protokollieren Sie bei der Diagnose von Ratenbegrenzungsproblemen den Unix-Zeitstempel x-ratelimit-reset zusammen mit der Antwort. Konvertieren Sie ihn in eine für Menschen lesbare Zeit, um nachzuvollziehen, wann das Zeitfenster wechselt.
Nächste Schritte
- Authentifizierungsablauf — Token abrufen, bevor API-Aufrufe getätigt werden
- curl-Schnellstart — Ratenbegrenzungs-Header in Aktion sehen