Ratenbegrenzungen

Eine Ratenbegrenzung begrenzt die Anfragenzahl in kurzer Zeit. Bei Überschreitung antwortet die API mit 429 („zu viele Anfragen“), statt die Arbeit auszuführen, und nennt die Wartezeit. Das schützt vor unkontrollierten Skripten; es ist kein Kontingent für die insgesamt erzeugbare Menge.

Grenzen im Überblick

Zwei Kontingente je Konto: Lesen und Schreiben

Die API, also /api/v1/* und kompatible /v1/*- und /v1beta/*-Endpunkte, wird je Konto begrenzt, nicht je Key. Andernfalls ließe sich die Grenze mit zusätzlichen Keys umgehen.

Lesen und Schreiben werden in zwei getrennten Kontingenten gleicher Größe gezählt. Die Standardschutzgrenze beträgt jeweils 1000 Anfragen je 10 Sekunden: ungefähr 100 dauerhafte RPS (Anfragen je Sekunde), mit einem kurzfristigen Aufkommen von 1000. Das ist ein übergreifender Schutz vor Missbrauch und unkontrollierten Clients, kein niedriges Kontingent für normale bezahlte Generierung.

Verwendet wird ein Token Bucket statt eines festen Zeitfensterzählers: Kapazität 1000, Auffüllung über 10 Sekunden, ungefähr 100 Tokens je Sekunde. Jede Anfrage verbraucht einen Token; sie werden kontinuierlich ergänzt. Anders als ein festes Fenster glättet dies die Auffüllung an Fenstergrenzen.

upload-url hat zusätzlich zum Schreibkontingent eine eigene übergreifende Grenze von 1000 Anfragen je 10 Sekunden. Sie schützt die Schreibautorisierung des Objektspeichers separat; normale Uploads sollten sich ihr nicht nähern.

usage hat dagegen zusätzlich zum Lesekontingent eine deutlich engere Grenze von 30 Anfragen je Minute. Es aggregiert historische Tasks und ist daher wesentlich aufwendiger als normales Lesen. Nutzen Sie es zur Abstimmung, nicht zum Polling. Dieses Kontingent gibt bei nicht verfügbarer Begrenzungsentscheidung immer 429 zurück; anders als andere Kontingente kann es nicht für die Weiterleitung trotz Ausfall konfiguriert werden.

Noch ungenutzte Upload-URLs

Separat kann ein Konto höchstens 128 noch ungenutzte Upload-URLs oder 1 GiB deklarierte Gesamtdateigröße halten. Eine weitere Anfrage liefert 429 mit Too many pending uploads; finish existing uploads before requesting more und ohne Retry-After.

Warten hilft hier nicht; lassen Sie keine allgemeine Wiederholungsschleife endlos laufen. Laden Sie angeforderte Dateien hoch und bestätigen sie, oder lassen ihre Upload-URLs nach etwa 20 Minuten ablaufen; der Platz wird unmittelbar frei. Meist fordert ein Skript URLs gesammelt an und verwendet sie nicht. Siehe Medien.

Alle Kontingente

Begrenzungen gelten je API-Bereich; jeder Bereich teilt eine Middlewarekette. Als API-Nutzer können Sie die ersten fünf erreichen:

Diese Standardzahlen können ohne neue Veröffentlichung geändert werden. Ihr aktuelles Kontingent steht immer im X-RateLimit-Limit-Header und in der Konsolen-Übersicht. Vertrauen Sie dem Header und codieren die Standards nicht fest im Client.

Antwortheader

Eine normale Antwort mit Standardkontingent enthält:

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

Wie eine Begrenzung aussieht

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

HTTP-Status 429 mit Retry-After.

Umgang damit

Lesen Sie Retry-After. Senden Sie nicht stur in festen Abständen. Die Beispiele stoppen nach fünf Versuchen und verhindern damit auch eine Endlosschleife beim oben beschriebenen 429 für ausstehende Uploads.

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")

Parallelität ist eine separate Frage

Laufende Tasks werden tatsächlich durch Folgendes begrenzt, nicht durch die Anfragerate:

• Verfügbares Guthaben: Jeder laufende Task reserviert Geld. Ist das Guthaben aufgebraucht, erhalten neue Tasks 40201.
• Ausgabenlimits: Tages-, Monats- und Gesamtlimit eines Keys, Tages- und Monatslimits eines Teams für dessen Keys sowie Plattformtageslimit. Jedes erreichte Limit liefert 40202. Siehe Ausgabenlimits.
• Ausführungskapazität: Kann ein Modell gar nicht laufen, folgt 50301.

Für mehr gleichzeitig laufende Tasks benötigen Sie deshalb meistens mehr Guthaben oder ein höheres Ausgabenlimit, kein höheres Ratenlimit.

Mehr Kontingent anfragen

Ihr Kontingent steht in der Konsolen-Übersicht. Öffnen Sie unter Support ein Gespräch zum Thema API-Integration und beschreiben Spitzenanfragen je Sekunde sowie Seriennutzung und maximale Seriengröße. Das beschleunigt die Prüfung.

Begrenzen Sie bis dahin die Clientparallelität und beachten Retry-After. Wählen Sie die Parallelität anhand Arbeitslast, Generierungsdauer und verfügbarem Guthaben, statt sie künstlich niedrig an ein Standardratenlimit anzupassen.

Wenn die Begrenzung selbst nicht verfügbar ist

Ratenbegrenzung hängt von einem externen Zähler ab. Bei Ausfall entscheidet die Konfiguration zwischen Weiterbedienen und Ablehnen zum Kontingentschutz. Ablehnen ist Standard: Nicht lesbare Konfiguration darf niemals als fehlendes Limit behandelt werden.

Bei Ablehnungsmodus erhalten Sie 429 mit Retry-After: 1, nicht 500. Das ist bewusst: 500 signalisiert einen Defekt und wird von vielen Client-SDKs sofort wiederholt, was einen Vorfall stärker belastet. 429 mit Retry-After fordert die nötige Pause.

Lesen Sie 429 deshalb nicht als Beweis zu hoher eigener Geschwindigkeit. Retry-After zu beachten, ist in beiden Fällen richtig.