Limites de débit et quotas

Deux types de limites gardent l’API rapide pour tout le monde :

• La limite de débit d’une clé : combien de requêtes par seconde elle peut envoyer, avec une rafale pour les pics de courte durée.
• Les quotas de l’organisation : combien de requêtes l’ensemble de ses clés peut envoyer par minute, par jour et par mois.

Les deux dépendent de l’offre de l’organisation. Chaque réponse vous indique où vous en êtes : un client bien conçu n’a jamais besoin de deviner.

Limite de débit d’une clé

Chaque clé dispose d’un débit régulier et d’une rafale. La rafale vous permet d’envoyer autant de requêtes d’un coup ; ensuite, les requêtes sont acceptées au débit régulier.

La classe découle de l’offre de l’organisation. GET /v1/me indique la classe, le débit et la rafale de la clé qui l’appelle (rate_limit). La limite s’applique à la clé dans son ensemble, quel que soit le nombre de serveurs de l’API qui traitent vos requêtes.

Les points de terminaison de flux, POST /v1/chat (avec ou sans "stream": true) et GET /v1/jobs/stream, sont hors de la limite de débit de la clé : ils ne la consomment pas, et leurs en-têtes RateLimit n’ont pas d’élément "key". Ils comptent en revanche dans les quotas de l’organisation, une fois chacun, au début de la requête. Les questions ont leurs propres limites, décrites ci-dessous.

Quotas de l’organisation

Une offre peut fixer des quotas de requêtes pour l’organisation : par minute, par jour et par mois. Les fenêtres sont des périodes calendaires en UTC : une minute commence à la seconde 00, un jour à 00:00 UTC, un mois le premier jour à 00:00 UTC. Chaque requête faite avec une clé ou un jeton OAuth de l’organisation compte, quelle que soit l’adresse. Une requête de flux compte une fois, à son début, quelle que soit sa durée ; quand un quota est épuisé, elle est refusée avec 429 comme toute autre requête. Une requête refusée avec 429 ne compte pas.

Les en-têtes

Chaque réponse à une requête faite avec une clé indique les limites qui s’y appliquent :

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy et RateLimit suivent le brouillon de l’IETF RateLimit header fields for HTTP. Chaque élément correspond à une limite :

X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset indiquent la plus stricte de ces limites sous une forme plus simple, pour les clients écrits avant l’apparition de RateLimit. X-RateLimit-Reset est exprimé en secondes.

Quand une limite est atteinte

L’API répond 429 Too Many Requests avec un en-tête Retry-After en secondes :

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Attendez la durée de Retry-After et répétez la requête. Répétez POST et PATCH avec la même clé d’idempotence. Les fonctions de nouvelle tentative de la page Erreurs font les deux.

D’autres limites de l’offre répondent aussi 429 avec Retry-After, par exemple le nombre de questions par jour (limits.questions) ou le nombre de réponses en cours en même temps (limits.concurrent_answers). Traitez-les de la même façon.

Rester sous les limites

• Lisez RateLimit et ralentissez quand r devient faible, au lieu d’attendre un 429.
• Étalez les traitements en masse dans le temps et utilisez les points de terminaison par lots quand ils existent : un lot de 100 documents compte pour une seule requête.
• N’interrogez pas l’API en boucle serrée pour détecter les modifications. Abonnez-vous aux webhooks, ou lisez le flux d’événements toutes les quelques secondes.
• Faites tourner les processus parallèles avec un limiteur de débit partagé. Plusieurs processus qui utilisent la même clé partagent la même limite de débit.
• Si votre intégration a besoin de davantage, demandez une classe supérieure à votre interlocuteur chez Sursa.