Limites de débit

L'API programmatique applique une limite de débit simple par compte, en plus du quota mensuel de crédits. Cette page présente cette limite, la manière dont elle est calculée et comment la contourner en douceur.

La limite#

Concrètement : une requête par seconde en moyenne, avec des pics pouvant atteindre 60 requêtes au cours d'une période de 60 secondes.

Lorsque vous dépassez la limite, la requête suivante renvoie :

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": "Rate limit exceeded. Max 60 requests per minute."
}

La requête 429 est elle-même enregistrée, ce qui est normal : elle sort du délai de 60 secondes comme n'importe quelle autre requête.

Fonctionnement de la fenêtre#

Le limiteur est une fenêtre glissante, et non un intervalle fixe :

1. À chaque requête, le serveur comptabilise le nombre de vos requêtes reçues au cours des 60 dernières secondes.
2. Si ce nombre est déjà ≥ 60, la demande est rejetée avec 429.
3. Sinon, le processus se poursuit, est consigné dans le journal et alimente les fenêtres futures.

Donc, une rafale de 60 requêtes à t = 0 s'éclaircit à t = 60, et non au début de la minute suivante. Il n'y a pas Retry-After en-tête — attendez environ 1 seconde et réessayez, ou procédez comme indiqué ci-dessous.

Stratégie de retrait#

Une boucle pragmatique :

async function withRetry(fn, { maxAttempts = 6, baseMs = 1000 } = {}) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const isRateLimited =
        /Rate limit exceeded/.test(err.message);
      const isUpstream5xx =
        /Upstream error/.test(err.message);

      if (!isRateLimited && !isUpstream5xx) throw err;
      if (attempt >= maxAttempts) throw err;

      const delay = baseMs * Math.pow(2, attempt - 1) + Math.random() * 250;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Remarques :

• Utiliser un recul exponentiel avec gigue. Un appartement setTimeout(1000) à chaque nouvelle tentative, il entrera en conflit avec lui-même si vous travaillez en parallèle.
• Ne pas réessayer sur 403, 404, 401, ou l'épuisement du crédit 429. Ils ne s'en remettront pas en une minute.
• Tentatives de mise en place. Six tentatives supplémentaires avec baseMs = 1000 Cela couvre déjà environ une minute de délai d'attente — si vous êtes toujours soumis à une limitation de débit après cela, cela signifie que vous maintenez un débit supérieur à 60 requêtes par minute et que vous avez besoin de moins de processus simultanés, et non de plus de tentatives.

Concevoir dans le respect des contraintes#

La limite s'applique par utilisateur, et non par adresse IP ou par clé ; la création de plusieurs clés n' augmente pas cette limite.

Limite de requêtes vs crédits#

En pratique, les charges de travail soutenues atteignent le quota de crédits bien avant la limite de débit. La limite de débit sert principalement à empêcher les boucles incontrôlées.

Déterminer la cause d'une erreur 429#

Tant la limite de taux par minute que la limite de crédit mensuelle renvoient un 429 code d'état. Vous pouvez les distinguer en examinant le corps de la réponse :

if (res.status === 429) {
  const body = await res.json();
  if (body && body.credits) {
    // Monthly credit limit reached.
    // Do not retry until next month or you upgrade your plan.
  } else {
    // Per-minute rate limit reached.
    // Implement a backoff strategy and retry.
  }
}

Consultez la section « Erreurs » pour obtenir la liste complète des codes d'état.

Erreurs courantes#

• Des nuits blanches. A pour boucle sans attendre L'intervalle entre les requêtes épuisera les 60 appels en quelques millisecondes et provoquera un blocage.
• Parallélisation sans limiteur commun. Deux processus de travail traitant chacun 40 éléments par minute déclencheront la limite, même si chacun semble « sans risque ».
• Réessayer 403 / 404 comme s'il s'agissait de limites de débit. Cela signifie « accès refusé » ou « chemin incorrect » ; ces tentatives échoueront tant que la requête ou le compte n'auront pas été modifiés.
• Sondage /générique pour détecter un facteur limitant. Cet appel d'API est pris en compte dans la limite de débit (et coûte un crédit). Consultez le nombre réel 429 au lieu de cela.