Limites de débit

Chaque clé d’API a une limite de débit, comptée par la passerelle placée devant l’API. Elle est actuellement de 600 requêtes par minute et par clé, comptées sur des fenêtres fixes d’une minute.

Les en-têtes de limite

Les réponses portent trois en-têtes :

• X-RateLimit-Limit : le nombre de requêtes qu’une fenêtre autorise.
• X-RateLimit-Remaining : combien il en reste dans la fenêtre en cours.
• X-RateLimit-Reset : le nombre de secondes avant la remise à zéro de la fenêtre.

Quand vous la dépassez

La passerelle répond 429 rate_limit_exceeded. Le corps est l’objet error habituel, de type rate_limit_error. Son request_id vaut null : la requête n’a jamais atteint l’API.

La passerelle protège aussi la plateforme contre les rafales venant d’une même adresse IP. Cette protection peut elle aussi répondre 429, sans les en-têtes X-RateLimit-*. Elle compte ensemble toutes les applications placées derrière la même adresse IP, quelles que soient leurs clés. Fiez-vous au statut et ralentissez de la même façon.

Ralentir

1. Attendez le nombre de secondes indiqué par X-RateLimit-Reset.
2. Réessayez. Si vous recevez une nouvelle 429, attendez plus longtemps à chaque fois : un délai exponentiel, avec un peu d’aléa pour que vos processus ne réessaient pas tous ensemble.

Rester sous la limite

• Étalez les grosses synchronisations dans le temps plutôt que de les envoyer d’un bloc.
• Utilisez limit=100 sur les listes : une requête renvoie jusqu’à 100 objets.
• Parcourez les listes vers l’avant avec starting_after : c’est aussi l’appel le moins coûteux. Voir Pagination.
• Utilisez une clé par application, pour que la rafale de l’une ne ralentisse pas l’autre.