Limite de Rată
API-ul VaultPAM aplică limite de rată pe client pentru a proteja stabilitatea serviciului. Toate răspunsurile API includ antetele x-ratelimit-* pentru ca clientul dumneavoastră să-și poată urmări consumul curent și să se retragă în mod gradat înainte de a atinge o limită.
Antetele de Răspuns
Fiecare răspuns API include următoarele antetele:
| Antet | Tip | Descriere |
|---|---|---|
x-ratelimit-limit | întreg | Numărul maxim de cereri permise în fereastra curentă |
x-ratelimit-remaining | întreg | Cereri rămase în fereastra curentă |
x-ratelimit-reset | Marcă temporală Unix (secunde) | Când se resetează fereastra curentă |
La un răspuns 429 Too Many Requests, se include un antet suplimentar:
| Antet | Tip | Descriere |
|---|---|---|
retry-after | întreg (secunde) | Timp minim de așteptare înainte de o nouă încercare |
Toate antetele utilizează nume cu litere mici.
Categorii de Limite de Rată
API-ul aplică limite diferite în funcție de tipul operațiunii și contextul apelantului. Antetele x-ratelimit-* din fiecare răspuns reflectă categoria de limită aplicabilă acelei cereri specifice.
Valori de referință (doar orientare — tratați antetele x-ratelimit-* ca fiind autoritare):
| Categorie | Limită |
|---|---|
| Încercări de autentificare pe IP | 60 pe minut |
| Cereri API pe IP | 300 pe minut |
| Cereri API pe utilizator autentificat | 120 pe minut |
| Operațiuni sensibile pe utilizator | 30 pe minut |
Limitele afișate mai sus documentează valorile implicite actuale. Utilizați valorile x-ratelimit-limit și x-ratelimit-remaining din fiecare răspuns pentru a lua decizii privind reîncercarea — numerele publicate pot fi supuse modificărilor fără notificare prealabilă.
Gestionarea Răspunsurilor 429
Când primiți un răspuns 429 Too Many Requests:
- Citiți valoarea antetului
retry-after(secunde). - Întrerupți bucla de cereri pentru cel puțin acea durată.
- Reîncercați cererea.
Exemplu de răspuns:
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."
}
Modele de Client Recomandate
Verificați bugetul rămas înainte de operațiuni în masă
Citiți x-ratelimit-remaining după fiecare răspuns. Dacă scade sub un prag (de exemplu, 10), introduceți o pauză înainte de cererea următoare pentru a evita declanșarea unui 429.
Backoff exponențial pentru 429-uri tranzitorii
Dacă retry-after nu este prezent sau primiți mai multe răspunsuri 429 consecutive, utilizați backoff exponențial cu jitter:
wait = min(base * 2^attempt + random_jitter, max_wait)
Înregistrați x-ratelimit-reset pentru depanare
La diagnosticarea problemelor de limite de rată, înregistrați marca temporală Unix x-ratelimit-reset alături de răspuns. Convertiți la o oră lizibilă de om pentru a înțelege când se resetează fereastra.
Pași Următori
- Flux de Autentificare — obțineți jetoane înainte de a efectua apeluri API
- curl Quickstart — vedeți antetele de limite de rată în acțiune