Limiti di velocità
L'API VaultPAM applica limiti di velocità per client al fine di proteggere la stabilità del servizio. Tutte le risposte API includono intestazioni x-ratelimit-* in modo che il client possa tracciare il consumo attuale e ridurre gradualmente il carico prima di raggiungere un limite.
Intestazioni di risposta
Ogni risposta API include le seguenti intestazioni:
| Intestazione | Tipo | Descrizione |
|---|---|---|
x-ratelimit-limit | numero intero | Numero massimo di richieste consentite nella finestra corrente |
x-ratelimit-remaining | numero intero | Richieste rimanenti nella finestra corrente |
x-ratelimit-reset | timestamp Unix (secondi) | Quando la finestra corrente si azzera |
In una risposta 429 Too Many Requests, è inclusa un'intestazione aggiuntiva:
| Intestazione | Tipo | Descrizione |
|---|---|---|
retry-after | numero intero (secondi) | Tempo minimo di attesa prima di riprovare |
Tutte le intestazioni utilizzano nomi in minuscolo.
Categorie di limiti di velocità
L'API applica limiti diversi a seconda del tipo di operazione e del contesto chiamante. Le intestazioni x-ratelimit-* in ogni risposta riflettono la categoria di limite applicabile a quella specifica richiesta.
Valori di riferimento (solo indicativi — considerare le intestazioni x-ratelimit-* come autoritativi):
| Categoria | Limite |
|---|---|
| Tentativi di accesso per IP | 60 al minuto |
| Richieste API per IP | 300 al minuto |
| Richieste API per utente autenticato | 120 al minuto |
| Operazioni sensibili per utente | 30 al minuto |
I limiti mostrati sopra documentano le impostazioni predefinite attuali. Utilizzare i valori x-ratelimit-limit e x-ratelimit-remaining in ogni risposta per decidere i tentativi — i numeri pubblicati sono soggetti a modifiche senza preavviso.
Gestione delle risposte 429
Quando ricevete una risposta 429 Too Many Requests:
- Leggete il valore dell'intestazione
retry-after(secondi). - Sospendete il ciclo di richieste per almeno quella durata.
- Riprovate la richiesta.
Esempio di risposta:
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."
}
Modelli di client consigliati
Verificare il budget rimanente prima delle operazioni in blocco
Leggete x-ratelimit-remaining dopo ogni risposta. Se scende al di sotto di una soglia (ad esempio, 10), introducete una pausa prima della richiesta successiva per evitare di attivare un 429.
Backoff esponenziale per 429 transitori
Se retry-after non è presente o ricevete più risposte 429 consecutive, utilizzate backoff esponenziale con jitter:
wait = min(base * 2^attempt + random_jitter, max_wait)
Registrare x-ratelimit-reset per il debug
Quando diagnosticate problemi di limite di velocità, registrate il timestamp Unix x-ratelimit-reset insieme alla risposta. Convertitelo in un'ora leggibile dall'uomo per comprendere quando la finestra si azzera.
Fasi successive
- Authentication Flow — acquisire i token prima di effettuare le chiamate API
- curl Quickstart — vedere le intestazioni di limite di velocità in azione