YouTube Transcript API Rate Limit: What It Is and How to Handle 429s

Ce sont deux contraintes différentes souvent confondues :

• Quota - total de requêtes autorisées sur une fenêtre plus longue (par ex. une journée). L'épuiser signifie attendre une réinitialisation, parfois à plusieurs heures d'écart.
• Limite de débit - requêtes autorisées par courte fenêtre (par ex. une minute). L'atteindre signifie ralentir de quelques secondes à une minute, pas des heures.

Sous le capot, la plupart des API implémentent la limitation de débit soit avec un token bucket (vous accumulez des "jetons" de requête à un rythme constant et en dépensez un par requête, permettant de courtes rafales), soit avec un compteur à fenêtre fixe ou glissante (un plafond strict par minute calendaire, réinitialisé à la limite). Le mécanisme utilisé par une API donnée change la manière dont votre trafic peut se permettre d'être en rafale - un token bucket tolère mieux un pic court qu'une fenêtre fixe.

429 Too Many Requests n'est pas un folklore propre à un fournisseur - il a été formellement défini dans la RFC 6585 (avril 2012) comme un code de statut HTTP standard. Selon la RFC 9110, un serveur conforme peut attacher un en-tête Retry-After à une réponse 429 (ou 503), sous l'une de ces deux formes :

• Forme délai en secondes - un entier, par ex. Retry-After: 120, signifiant attendre 120 secondes.
• Forme date HTTP - un horodatage absolu, par ex. Retry-After: Wed, 21 Oct 2026 07:28:00 GMT.

Lorsqu'il est présent, cet en-tête fait autorité - le serveur vous indique exactement quand il acceptera de nouvelles requêtes. N'ajoutez pas votre propre backoff exponentiel par-dessus ; cela ne fait que retarder davantage votre reprise. Ne recourez au backoff que lorsque l'en-tête est absent.

Le bon ordre des opérations : vérifiez d'abord Retry-After, et ne recourez au backoff exponentiel avec jitter que s'il est absent. Le jitter (randomiser légèrement le délai) compte car lorsque de nombreux clients atteignent une limite simultanément et réessaient tous selon un calendrier identique, ils se synchronisent et créent une "ruée" qui redéclenche immédiatement la même limite.

Node.js :

async function getTranscriptWithRetry(videoId, apiKey, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(
      `https://getyoutubetranscript.com/api/v1/transcript?v=${videoId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    if (res.status !== 429) return res.json();

    const retryAfter = res.headers.get('retry-after');
    const waitMs = retryAfter
      ? Number(retryAfter) * 1000
      : 500 * 2 ** attempt + Math.random() * 250; // exponential backoff + jitter
    await new Promise((r) => setTimeout(r, waitMs));
  }
  throw new Error('Rate limited after retries');
}

Python :

import os, time, random, requests

def get_transcript_with_retry(video_id, api_key, max_retries=4):
    url = "https://getyoutubetranscript.com/api/v1/transcript"
    for attempt in range(max_retries + 1):
        res = requests.get(url, params={"v": video_id}, headers={"Authorization": f"Bearer {api_key}"})
        if res.status_code != 429:
            return res.json()

        retry_after = res.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else (0.5 * 2 ** attempt + random.uniform(0, 0.25))
        time.sleep(wait)
    raise RuntimeError("Rate limited after retries")

Un plafond de requêtes par minute et un plafond de concurrence en vol ne sont pas la même chose. Déclencher 50 requêtes simultanément avec Promise.all peut provoquer un 429 même si votre total pour la minute est bien en dessous du budget, car le serveur (ou un proxy devant lui) peut aussi plafonner les connexions simultanées. Lors du traitement en lot de nombreuses vidéos, limitez la concurrence indépendamment de votre backoff de limite de débit :

import pLimit from 'p-limit';

const limit = pLimit(5); // at most 5 requests in flight at once
const results = await Promise.all(
  videoIds.map((id) => limit(() => getTranscriptWithRetry(id, apiKey)))
);

Pour des lots soutenus à fort volume, passer à une offre supérieure augmente directement le plafond de req/min - consultez les tarifs dans la documentation API, ou démarrez avec 100 crédits gratuits depuis le tableau de bord.