Ratenbegrenzungen

Anfragelimits je Tarif für Listings und Social, das Format der 429-Antwort und das Vorgehen bei Wartezeiten und Wiederholungsversuchen.

Die Listings API zählt Anfragen pro Konto und rechnet sie auf das Anfragelimit Ihres Tarifs an. Solange Sie das Limit einhalten, bleibt Ihre Integration reaktionsfähig; bei einer Überschreitung gibt die API 429 Too Many Requests mit allen Informationen zurück, die Sie für einen kontrollierten erneuten Versuch benötigen.

Limits nach Tarif

Sie testen die API ohne kostenpflichtigen Tarif? Der kostenlose Sandbox-Tagespass liefert beim Start des Tagespasses zusammen mit dem API-Schlüssel die aktuell geltenden Anfragelimits zurück.

Die Limits richten sich nach dem Tarif und gelten pro Konto: Alle API-Schlüssel eines Kontos nutzen dasselbe Kontingent. Anfragen werden in drei Zeitfenstern gezählt: mit einem Limit für kurzfristige Lastspitzen pro Minute, einem stündlichen Limit und einer täglichen Obergrenze. Jede Anfrage wird unabhängig vom Endpunkt gleich gezählt. Eine kostenlose Testphase läuft mit dem von Ihnen gewählten Tarif, sodass dessen Limits ab der ersten Anfrage gelten.

TarifLimit pro MinuteLimit pro StundeTägliches Limit
Launch10 Anfragen/min600 Anfragen/Stunde7.200 Anfragen/Tag
Growth50 Anfragen/min3.000 Anfragen/Stunde36.000 Anfragen/Tag
EnterpriseVertraglich festgelegtVertraglich festgelegtVertraglich festgelegt

Social nutzt dasselbe Kontingent

Anfragen an Social-Endpunkte werden auf dasselbe Anfragekontingent pro Konto angerechnet wie alle anderen Anfragen. Ein POST /social/bulk-posts mit 500 Zeilen zählt als eine Anfrage, nicht als 500. Daher benötigen Sie beim gebündelten Laden vieler Inhalte die wenigsten Anfragen.

Listings und Social sind separate Abonnements, haben jedoch keine separaten Kontingente. Für ein Konto mit beiden Abonnements gelten die höheren Limits der beiden Tarifstufen, einmalig über alle Endpunkte hinweg — weder die Summe noch ein Kontingent pro Produkt. Für einen Kunden mit Listings Launch und Social Growth gelten die oben aufgeführten Growth-Limits für sämtliche Anfragen.

Die 429-Antwort

Wenn Sie ein Limit überschreiten, gibt die API HTTP 429 und die standardmäßige Fehlerantwort zurück. Drei Felder sind für erneute Versuche relevant:

  • retry_after_seconds: die Wartezeit bis zum nächsten Versuch. Der HTTP-Header Retry-After enthält denselben Wert, sofern er vorhanden ist.
  • correlation_id: eine Anfragekennung, die Sie bei einer Kontaktaufnahme mit dem Support angeben sollten.
  • doc_url: ein Link zum Eintrag rate_limited in der Fehlercode-Referenz.
JSON
{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

429-Antworten mit Backoff behandeln

Beachten Sie retry_after_seconds, sofern vorhanden, und verwenden Sie andernfalls exponentielles Backoff: Verdoppeln Sie die Wartezeit bei jedem aufeinanderfolgenden 429 bis zu einer Obergrenze und fügen Sie eine kleine zufällige Abweichung hinzu, damit mehrere Clients ihre Anfragen nicht gleichzeitig wiederholen.

Python
import randomimport time import requests MAX_RETRIES = 5  def get_with_backoff(url: str, headers: dict, max_retries: int = MAX_RETRIES):    for attempt in range(max_retries):        resp = requests.get(url, headers=headers)        if resp.status_code != 429:            resp.raise_for_status()            return resp.json()         # Prefer the server's hint; fall back to exponential backoff + jitter.        body = resp.json().get("error", {})        retry_after = body.get("retry_after_seconds")        if retry_after is None:            retry_after = min(2 ** attempt, 30) + random.uniform(0, 1)        time.sleep(retry_after)     raise RuntimeError("Still rate limited after retrying")

Unter dem Limit bleiben

  • Fragen Sie einen listings scan höchstens einmal alle 15 Sekunden ab und verwenden Sie vorzugsweise den Webhook listing_scan.completed, der den abgeschlossenen Scan ohne wiederholte Abfragen liefert. Ein Scan dauert mehrere Minuten, daher verbraucht eine häufigere Abfrage lediglich Anfragen.

  • Fordern Sie jeweils nur eine Seite an: Schleifen, die Seiten in rascher Folge parallel abrufen, sind die häufigste Ursache für 429-Antworten. Lesen Sie pageInfo.hasNextPage und rufen Sie die nächste Seite erst ab, wenn die aktuelle Seite zurückgegeben wurde.

  • Filtern Sie serverseitig mit dem Abfrageparameter filter, anstatt jede Seite abzurufen und Zeilen clientseitig zu verwerfen.

  • Speichern Sie Antworten, die sich selten ändern, im Cache, anstatt sie bei jeder Anfrage erneut abzurufen.