Limites de débit

#La limite

Chaque clé peut faire 120 appels par minute. L’API REST et le serveur MCP comptent dans la même fenêtre : un assistant IA et une synchronisation qui partagent une clé partagent aussi sa limite. Donnez-leur une clé chacun.

Une synchronisation qui lit 500 participants par page en lit 60 000 sans dépasser la limite : une intégration bien conçue l’atteint donc rarement. Une boucle qui redemande sans cesse la même chose l’atteint en moins d’une minute, et c’est précisément son rôle.

#Où vous en êtes

Chaque réponse, refus compris, indique la limite sous deux formes : les en-têtes RateLimit de l’IETF et les en-têtes X-RateLimit-* que lisent la plupart des bibliothèques clientes.

HTTP/1.1 200 OK
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=117;t=42
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42

r (remaining) est le nombre d’appels restants dans cette fenêtre, et t le nombre de secondes avant le début d’une nouvelle fenêtre.

#En cas de dépassement

L’appel est refusé avec 429 Too Many Requests, un en-tête Retry-After en secondes et un problème avec "code": "rateLimited". Rien n’a été fait : attendez, puis renvoyez-le. Un appel refusé figure dans l’activité des clés, pour que vous puissiez voir quand c’est arrivé.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/problem+json

{ "status": 429, "code": "rateLimited", "detail": "This key made more than 120 calls in a minute. Try again in 18 seconds; the RateLimit header says what is left." }

#Rester largement en dessous

• Demandez de grandes pages : limit=500 ne pose aucun problème.
• Synchronisez avec updatedSince au lieu de tout relire à chaque fois (Pagination et synchronisation).
• Utilisez les webhooks plutôt que d’interroger l’API pour savoir ce qui vient de se passer.
• Envoyez If-None-Match avec l’ETag dont vous disposez : un 304 est rapide, même s’il compte quand même.
• Faites une pause quand le r de RateLimit devient bas, plutôt que d’attendre d’être refusé.

La fenêtre est comptée par serveur : un jour de forte affluence, une clé peut donc de temps en temps obtenir un peu plus que la limite. Ne comptez pas là-dessus : considérez les en-têtes comme la seule référence.