Limites de débit
L'API VaultPAM applique des limites de débit par client afin de protéger la stabilité du service. Toutes les réponses de l'API incluent des en-têtes x-ratelimit-* pour que votre client puisse suivre sa consommation actuelle et lever le pied progressivement avant d'atteindre une limite.
En-têtes de réponse
Chaque réponse de l'API inclut les en-têtes suivants :
| En-tête | Type | Description |
|---|---|---|
x-ratelimit-limit | entier | Nombre maximal de requêtes autorisées dans la fenêtre actuelle |
x-ratelimit-remaining | entier | Requêtes restantes dans la fenêtre actuelle |
x-ratelimit-reset | horodatage Unix (secondes) | Moment où la fenêtre actuelle se réinitialise |
Sur une réponse 429 Too Many Requests, un en-tête supplémentaire est inclus :
| En-tête | Type | Description |
|---|---|---|
retry-after | entier (secondes) | Temps minimal à attendre avant de réessayer |
Tous les en-têtes utilisent des noms en minuscules.
Catégories de limites de débit
L'API applique des limites différentes selon le type d'opération et le contexte d'appel. Les en-têtes x-ratelimit-* de chaque réponse reflètent la catégorie de limite applicable à cette requête spécifique.
Valeurs de référence (à titre indicatif uniquement — considérez les en-têtes x-ratelimit-* comme faisant autorité) :
| Catégorie | Limite |
|---|---|
| Tentatives de connexion par IP | 60 par minute |
| Requêtes de l'API par IP | 300 par minute |
| Requêtes de l'API par utilisateur authentifié | 120 par minute |
| Opérations sensibles par utilisateur | 30 par minute |
Les limites indiquées ci-dessus documentent les valeurs par défaut actuelles. Utilisez les valeurs x-ratelimit-limit et x-ratelimit-remaining de chaque réponse pour décider de réessayer — les chiffres publiés sont susceptibles de changer sans préavis.
Gérer les réponses 429
Lorsque vous recevez une réponse 429 Too Many Requests :
- Lisez la valeur de l'en-tête
retry-after(secondes). - Suspendez votre boucle de requêtes pendant au moins cette durée.
- Réessayez la requête.
Exemple de réponse :
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."
}
Modèles client recommandés
Vérifier le budget restant avant les opérations en masse
Lisez x-ratelimit-remaining après chaque réponse. S'il descend en dessous d'un seuil (par exemple 10), introduisez une pause avant la requête suivante pour éviter de déclencher un 429.
Backoff exponentiel pour les 429 transitoires
Si retry-after est absent ou si vous recevez plusieurs réponses 429 consécutives, utilisez un backoff exponentiel avec gigue :
wait = min(base * 2^attempt + random_jitter, max_wait)
Journaliser x-ratelimit-reset pour le débogage
Lorsque vous diagnostiquez des problèmes de limite de débit, journalisez l'horodatage Unix x-ratelimit-reset avec la réponse. Convertissez-le en une heure lisible par un humain pour comprendre quand la fenêtre bascule.
Étapes suivantes
- Flux d'authentification — obtenez des jetons avant d'effectuer des appels à l'API
- Démarrage rapide curl — voyez les en-têtes de limite de débit en action