Limites de débit

Une limite de débit fixe le nombre de requêtes que vous pouvez envoyer sur une courte période. Si vous la dépassez, l’API répond 429 (« trop de requêtes ») au lieu d’exécuter le travail et indique combien de temps attendre. C’est une protection contre les scripts incontrôlés, pas un quota sur la quantité que vous pouvez générer.

Les limites en un coup d’œil

Deux quotas par compte : lectures et écritures

L’API, avec toutes les adresses sous /api/v1/* et les points de terminaison compatibles /v1/* et /v1beta/*, est limitée par compte, pas par clé : une limite par clé pourrait être contournée en créant davantage de clés.

Lectures et écritures sont comptées dans deux quotas distincts de même capacité. Le seuil de protection par défaut est de 1 000 requêtes par 10 secondes pour chacun : environ 100 RPS soutenues (requêtes par seconde), avec une rafale de 1 000. C’est une protection générale contre les abus et les clients incontrôlés, pas un faible quota pour le trafic normal de génération payante.

Le mécanisme est un seau à jetons, pas un compteur à fenêtre fixe : une capacité de 1 000, reconstituée sur 10 secondes, soit environ 100 jetons par seconde. Chaque requête prend un jeton, et les jetons reviennent régulièrement. Contrairement à une fenêtre fixe, ce mécanisme lisse le réapprovisionnement aux frontières des fenêtres.

upload-url dispose de sa propre protection générale de 1 000 requêtes par 10 secondes, en plus du quota d’écriture ci-dessus. Elle protège séparément l’autorisation d’écriture dans le stockage d’objets ; les envois normaux ne devraient pas l’approcher.

usage a une protection supplémentaire nettement plus stricte : 30 requêtes par minute, en plus du quota de lecture. Cet appel agrège les tâches historiques et coûte bien plus qu’une lecture ordinaire : la protection générale seule ne suffit pas. Utilisez-le pour le rapprochement, pas comme point de polling. Ce quota ne laisse jamais passer les requêtes par défaut : lorsque la décision de limitation est indisponible, il renvoie toujours 429, alors que d’autres quotas peuvent être configurés pour laisser passer le trafic.

URL d’envoi pas encore utilisées

Séparément, un compte peut détenir au maximum 128 URL d’envoi non utilisées, ou 1 GiB de taille de fichiers déclarée au total. Une demande supplémentaire renvoie 429 avec Too many pending uploads; finish existing uploads before requesting more, sans Retry-After.

Attendre ne suffit pas ici : ne laissez pas une boucle générique de nouvelles tentatives tourner sur cette erreur. Envoyez et validez les fichiers déjà demandés, ou laissez expirer leurs URL d’envoi, ce qui prend environ 20 minutes ; la capacité est alors immédiatement libérée. Généralement, un script a demandé des URL en masse sans les utiliser. Voir Médias.

Tous les quotas

Les limites s’appliquent par ensemble d’API : toutes les adresses d’un même ensemble partagent une chaîne de middleware. Comme utilisateur de l’API, vous pouvez rencontrer les cinq premiers quotas :

Ces valeurs sont des paramètres par défaut que nous pouvons modifier sans publier une nouvelle version. Votre capacité actuelle figure toujours dans l’en-tête X-RateLimit-Limit et sur la page Vue d’ensemble de la console. Fiez-vous à l’en-tête et ne codez pas les valeurs par défaut en dur dans votre client.

En-têtes de réponse

Une réponse normale d’un compte avec la capacité par défaut contient :

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

À quoi ressemble une limite atteinte

{
  "code": 429,
  "msg": "Too many requests. Retry in a moment",
  "request_id": "req_…"
}

Statut HTTP 429, avec Retry-After.

Gérer les limites

Lisez Retry-After. N’insistez pas à intervalle fixe. Les exemples s’arrêtent après cinq tentatives, évitant aussi qu’un 429 de fichiers en attente ne provoque une boucle infinie.

async function callRespectingLimits(url, init) {
  for (let i = 0; i < 5; i++) {
    const res = await fetch(url, init);

    if (res.status !== 429) return res;

    // The server already told you how long to wait; don't guess
    const wait = Number(res.headers.get('retry-after') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('persistently rate-limited');
}

import time, requests


def call_respecting_limits(method: str, url: str, **kwargs) -> requests.Response:
    for _ in range(5):
        res = requests.request(method, url, **kwargs)

        if res.status_code != 429:
            return res

        # The server already told you how long to wait; don't guess
        time.sleep(float(res.headers.get("retry-after", 1)))

    raise RuntimeError("persistently rate-limited")

La concurrence est une autre question

Ce qui limite réellement les tâches en cours, indépendamment du débit :

• Le solde disponible : chaque tâche en cours réserve des fonds. Quand le solde est épuisé, les nouvelles tâches reçoivent 40201.
• Les plafonds de dépenses : plafond quotidien, mensuel ou total de la clé, limites quotidiennes et mensuelles d’une équipe pour ses clés, et plafond quotidien de la plateforme. Atteindre n’importe lequel renvoie 40202. Voir Plafonds de dépenses.
• La capacité d’exécution : lorsqu’un modèle ne peut pas s’exécuter du tout, vous recevez 50301.

Pour « avoir davantage de tâches en cours simultanément », il faut donc généralement ajouter des fonds ou relever un plafond de dépenses, pas augmenter la limite de débit.

Demander une capacité supérieure

Votre capacité actuelle figure sur la page Vue d’ensemble de la console. Pour demander plus, ouvrez une conversation dans Support, rubrique Intégration API, et décrivez votre trafic : pic de requêtes par seconde, utilisation de lots et taille maximale d’un lot. Cela accélère considérablement l’examen.

En attendant, bornez la concurrence de votre client et respectez Retry-After. Choisissez cette borne selon la charge, le temps de génération et le solde disponible, plutôt que de la fixer artificiellement bas pour l’adapter à la limite de débit par défaut.

Lorsque le limiteur est lui-même indisponible

La limitation dépend d’un compteur externe. En cas de panne, le comportement configuré décide du résultat : autoriser pour continuer à servir, ou refuser pour protéger le quota. Le refus est le comportement par défaut : « impossible de lire la configuration » ne doit jamais devenir « aucune limite ».

Dans ce mode de refus, vous recevez 429 avec Retry-After: 1, pas 500. C’est délibéré : 500 signifie « nous sommes en panne », et la plupart des SDK clients réessaient immédiatement, ajoutant de la charge pendant un incident. 429 avec Retry-After signifie « attendez avant de revenir », ce qui est nécessaire ici.

N’interprétez donc pas 429 comme la preuve d’un rythme excessif de votre part. Respecter Retry-After est la bonne réponse dans les deux cas.