Limites de débit
Chaque requête est comptée dans une fenêtre fixe de 60 secondes. Le compteur appliqué dépend de votre mode d'authentification : les clés API disposent du budget le plus large, les sessions connectées d'un budget confortable, le trafic anonyme d'un petit budget. Une fois le budget épuisé, l'API répond 429 et vous indique combien de temps attendre.
Les trois buckets
Le limiteur choisit exactement un bucket par requête. Les limites ci-dessous sont les valeurs par défaut ; l'opérateur peut les ajuster, lisez donc les en-têtes de réponse plutôt que de figer des chiffres dans votre code.
apiKey | par clé API | 1000 requêtes / min |
authenticated | par utilisateur (session) | 600 requêtes / min |
anonymous | par IP du client | 30 requêtes / min |
Les chemins de santé et de documentation (/health, /meta/version, /docs et /openapi) ne sont jamais limités.
En-têtes de réponse
Chaque route limitée annonce sa politique dans la réponse :
X-RateLimit-Limit | Requêtes autorisées dans la fenêtre courante pour votre bucket. |
X-RateLimit-Window-Seconds | Durée de la fenêtre en secondes (60). |
X-RateLimit-Bucket | Le bucket appliqué : anonymous, authenticated ou apiKey. |
Retry-After | Uniquement sur un 429 : secondes à attendre avant de réessayer. |
Les réponses réussies portent aussi des variantes par bucket, suffixées de son nom, p. ex. X-RateLimit-Remaining-apiKey (requêtes restantes dans la fenêtre) et X-RateLimit-Reset-apiKey (secondes avant la remise à zéro de la fenêtre).
La réponse 429
Une requête limitée renvoie l'enveloppe d'erreur standard avec le code stable RATE_LIMITED. Construisez votre logique autour du code, affichez le message.
{ "error": { "code": "RATE_LIMITED", "message": "ThrottlerException: Too Many Requests", "traceId": "01JGME0Z4E8B3T3Y5F0V9K2QRD" }}Réessayer avec un backoff exponentiel
Respectez Retry-After lorsqu'il est présent et, à défaut, espacez vos tentatives de façon exponentielle. Associez les nouvelles tentatives de requêtes de mutation à un Idempotency-Key afin qu'un rejeu ne puisse jamais créer de doublon.
async function callWithRetry(request, maxRetries = 3) { for (let attempt = 0; ; attempt++) { const res = await request(); if (res.status !== 429 || attempt === maxRetries) return res; const seconds = Number(res.headers.get('Retry-After') ?? 2 ** attempt); await new Promise((resolve) => setTimeout(resolve, seconds * 1000)); }}Surfaces plus strictes
- Les endpoints d'IA (chat, reçus, voix, exports) empilent un second limiteur indexé par utilisateur et foyer : un palier de rafale de 10 requêtes par minute plus un palier soutenu de 200 par heure par défaut.
- Les endpoints d'authentification sous /auth/* exécutent leur propre limiteur anti-force brute : 10 tentatives par IP et par minute et 5 par compte, avec un verrouillage exponentiel pouvant atteindre une heure, et répondent 429 avec le code TOO_MANY_REQUESTS.
- Toutes les limites sont réglables par l'opérateur. Considérez les en-têtes de réponse, et non les chiffres de cette page, comme la source de vérité.