Limity zapytań
API VaultPAM wymusza limity zapytań dla poszczególnych klientów, aby chronić stabilność usługi. Wszystkie odpowiedzi API zawierają nagłówki x-ratelimit-*, dzięki czemu Twój klient może śledzić bieżące zużycie i płynnie ograniczać tempo przed osiągnięciem limitu.
Nagłówki odpowiedzi
Każda odpowiedź API zawiera następujące nagłówki:
| Nagłówek | Typ | Opis |
|---|---|---|
x-ratelimit-limit | liczba całkowita | Maksymalna liczba zapytań dozwolona w bieżącym oknie |
x-ratelimit-remaining | liczba całkowita | Liczba zapytań pozostałych w bieżącym oknie |
x-ratelimit-reset | znacznik czasu Unix (sekundy) | Moment zresetowania bieżącego okna |
W odpowiedzi 429 Too Many Requests dołączany jest dodatkowy nagłówek:
| Nagłówek | Typ | Opis |
|---|---|---|
retry-after | liczba całkowita (sekundy) | Minimalny czas oczekiwania przed ponowną próbą |
Wszystkie nagłówki używają nazw pisanych małymi literami.
Kategorie limitów zapytań
API stosuje różne limity w zależności od typu operacji oraz kontekstu wywołania. Nagłówki x-ratelimit-* w każdej odpowiedzi odzwierciedlają kategorię limitu mającą zastosowanie do danego, konkretnego zapytania.
Wartości referencyjne (wyłącznie orientacyjne — traktuj nagłówki x-ratelimit-* jako wiążące):
| Kategoria | Limit |
|---|---|
| Próby logowania na IP | 60 na minutę |
| Zapytania API na IP | 300 na minutę |
| Zapytania API na uwierzytelnionego użytkownika | 120 na minutę |
| Operacje wrażliwe na użytkownika | 30 na minutę |
Limity pokazane powyżej dokumentują bieżące wartości domyślne. Do podejmowania decyzji o ponownej próbie używaj wartości x-ratelimit-limit i x-ratelimit-remaining z każdej odpowiedzi — opublikowane liczby mogą ulec zmianie bez powiadomienia.
Obsługa odpowiedzi 429
Gdy otrzymasz odpowiedź 429 Too Many Requests:
- Odczytaj wartość nagłówka
retry-after(sekundy). - Wstrzymaj pętlę zapytań na co najmniej ten czas.
- Ponów zapytanie.
Przykładowa odpowiedź:
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."
}
Zalecane wzorce po stronie klienta
Sprawdzaj pozostały budżet przed operacjami masowymi
Odczytuj x-ratelimit-remaining po każdej odpowiedzi. Jeśli wartość spadnie poniżej progu (na przykład 10), wprowadź pauzę przed kolejnym zapytaniem, aby uniknąć wywołania odpowiedzi 429.
Wykładnicze wycofanie dla przejściowych odpowiedzi 429
Jeśli nagłówek retry-after nie występuje lub otrzymujesz wiele kolejnych odpowiedzi 429, zastosuj wykładnicze wycofanie (exponential backoff) z losowym rozproszeniem (jitter):
wait = min(base * 2^attempt + random_jitter, max_wait)
Rejestruj x-ratelimit-reset na potrzeby diagnostyki
Diagnozując problemy z limitami zapytań, rejestruj znacznik czasu Unix x-ratelimit-reset wraz z odpowiedzią. Przekonwertuj go na czytelny dla człowieka format, aby zrozumieć, kiedy okno się odnawia.
Następne kroki
- Przepływ uwierzytelniania — uzyskaj tokeny przed wykonaniem wywołań API
- Szybki start z curl — zobacz nagłówki limitów zapytań w działaniu