Limites de débit

L’API est soumise à une limitation de débit afin de rester rapide et équitable pour tous. Les limites sont appliquées à l’aide d’un algorithme de seau percé (leaky bucket) et sont agrégées par restaurant (sur l’ensemble des clés d’API de ce restaurant).

Les limites

Limite	Valeur
Débit soutenu	~2 requêtes par seconde
Rafale	jusqu’à 60 requêtes
Plafond quotidien	~25 000 requêtes par jour

Le seau percé vous laisse brièvement effectuer une rafale jusqu’à 60 requêtes, puis se vide au débit soutenu — ainsi un trafic régulier autour de 2 req/s s’écoule sans à-coups, tandis que les pics sont lissés plutôt que bloqués net dès la première requête supplémentaire.

En-têtes de limite de débit

Les réponses réussies portent l’état actuel de la limite afin que vous puissiez réguler votre rythme :

RateLimit-Limit: 60
RateLimit-Remaining: 42
RateLimit-Reset: 9

En-tête	Signification
RateLimit-Limit	La capacité du seau (taille de la rafale).
RateLimit-Remaining	Le nombre de requêtes que vous pouvez encore effectuer maintenant.
RateLimit-Reset	Le nombre de secondes avant que la capacité ne soit entièrement reconstituée.

Lorsque vous êtes limité

Dépasser la limite renvoie 429 Too Many Requests avec un en-tête Retry-After (le nombre de secondes à attendre) et une enveloppe rate_limit_error :

HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 1

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after 1 second.",
    "doc_url": "https://docs.useservice.app/api/errors#rate_limited"
  }
}

Rester dans les limites

• Respectez Retry-After. Sur un 429, attendez le nombre de secondes indiqué avant de réessayer.
• Reculez de façon exponentielle en cas de 429 répétés, avec un peu de gigue (jitter).
• Surveillez RateLimit-Remaining et ralentissez avant d’atteindre zéro.
• Synchronisez de façon incrémentale. Utilisez updated_since au lieu de relire sans cesse des collections entières, et préférez les webhooks aux boucles de sondage serrées.