Limites de débit

Par organisation, par minute, en deux classes de coût. Les limites existent pour arrêter une boucle incontrôlée, pas pour façonner le trafic ordinaire.

Les limites s’appliquent par organisation, par fenêtre fixe d’une minute, et sont comptabilisées dans deux compartiments selon la méthode de la requête :

Les deux sont bien au-delà de ce qu’utilise une intégration ordinaire. Une synchronisation nocturne qui pagine un catalogue de 5 000 produits à 100 par page effectue 50 lectures ; un import de 2 000 produits représente une seule écriture.

En-têtes HTTP

Chaque réponse porte l’état du compartiment dans lequel elle a été comptabilisée :

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1756910040

X-RateLimit-Reset est exprimé en secondes Unix.

Fonctionnement de la fenêtre

La fenêtre est une minute d’horloge fixe, pas une fenêtre glissante. Chaque fenêtre démarre à la minute pile (:00), le compteur revient à zéro à sa fin, et X-RateLimit-Reset indique le début de la fenêtre suivante. Toutes les clés d’une même organisation partagent la fenêtre.

Deux conséquences à connaître :

• Un débit régulier inférieur ou égal à la limite ne la déclenche jamais, quelle que soit la répartition dans la minute : 60 écritures envoyées dans la première seconde d’une fenêtre passent, tout comme 60 réparties sur la minute.
• Une rafale qui chevauche une frontière peut brièvement dépasser le débit nominal : jusqu’à 60 écritures dans les dernières secondes d’une fenêtre et 60 de plus dans les premières secondes de la suivante. Ne comptez pas sur cette marge ; dimensionnez votre boucle sur la limite.

Lorsque vous dépassez une limite

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limit_exceeded",
    "message": "Rate limit of 60 write requests per minute exceeded for this organization. Retry after 23s."
  }
}

La réponse porte Retry-After en secondes ; attendez ce délai puis réessayez. Un 429 n’est pas un échec de l’opération. Rien n’a été créé, aucun crédit n’a été dépensé et aucune Idempotency-Key n’a été consommée : il est donc toujours sûr de réessayer avec la même requête.

Interrogation périodique

GET /v1/imports/{id} et GET /v1/exports/{id} portent Retry-After: 5 tant qu’un job est en cours. Interroger à cet intervalle maintient même une boucle serrée largement à l’intérieur du compartiment de lectures. Un webhook supprime tout besoin d’interrogation.