Limits und Kontingent

Zwei Zahlen, von denen eine abweist

Ein Monatsvolumen ist das, was Ihr Tarif enthält, und ein Spitzenlimit begrenzt Anfragen pro Sekunde, damit ein Client die anderen nicht verdrängt.

Nur das Spitzenlimit weist eine Anfrage ab. Wer über das enthaltene Volumen hinausgeht, wird nicht abgeschnitten: Ihre Anbindung läuft weiter, und Verkehr, der sich dauerhaft deutlich über dem einpendelt, wofür Sie zahlen, ist ein Gespräch über einen höheren Tarif zur nächsten Verlängerung und kein 429 um drei Uhr nachts. Schreiben Sie Ihren Client gegen das Spitzenlimit; die Monatszahl ist die Größe des Tarifs, den Sie gekauft haben.

Beide legt Ihr Tarif fest. Den aktuellen Verbrauch finden Sie auf der Schlüsselseite und über GET /v1/api/me; die Tarifwerte stehen auf der Seite für Unternehmen.

Header

Jede Antwort trägt Ihren aktuellen Stand, ein gut erzogener Client kann also langsamer werden, bevor er abgewiesen wird, und nicht erst danach.

RateLimit-Limit: 100000
RateLimit-Remaining: 58796
RateLimit-Reset: 1725148800
RateLimit-Policy: 100000;w=2592000, 20;w=1

Richtig warten

async function call(request, attempts = 5) {
    for (let attempt = 0; attempt < attempts; attempt++) {
        const response = await fetch(request);

        if (response.status !== 429 && response.status < 500) {
            return response;
        }

        // Der Server weiß, wann er Sie wieder hereinlässt. Glauben Sie ihm.
        const retryAfter = Number(response.headers.get("Retry-After") ?? 0);
        const backoff = retryAfter > 0
            ? retryAfter * 1000
            : Math.min(2 ** attempt * 250, 30_000);

        // Ohne Streuung versucht es eine Flotte von Arbeitern im Gleichschritt
        // erneut und erzeugt genau die Spitze wieder, die zur 429 geführt hat.
        await sleep(backoff + Math.random() * 500);
    }

    throw new Error("Exhausted retry budget");
}

Weniger Kontingent verbrauchen

• Nutzen Sie Webhooks. Eine Zustellung kostet kein Kontingent. Einen Markt alle fünf Minuten abzufragen, um eine Änderung zu erwischen, die zweimal täglich passiert, ist die häufigste Quelle verschwendeter Anfragen.
• Fragen Sie nur nach Änderungen. updated_since macht aus einem vollständigen erneuten Lesen eine Handvoll Datensätze.
• Senden Sie If-None-Match. Eine 304 zählt nicht gegen Ihr Kontingent.
• Blättern Sie in größeren Schritten. Eine Anfrage über 200 Datensätze kostet eine Anfrage; vier über je 50 kosten vier.
• Erweitern Sie, statt zu folgen. expand=images erspart eine zusätzliche Anfrage je Objekt.
• Testen Sie mit Testschlüsseln. Ein sk_test_-Schlüssel zieht nicht am Live-Kontingent, eine laute CI-Suite kostet also nichts.

Wenn Sie mehr brauchen

Sagen Sie uns, was Sie bauen, statt das Limit zu umgehen. Dauerhaft hohes Volumen ist meist besser über einen Export bedient als über schnelleres Durchlaufen, und wir erhöhen lieber ein Kontingent, als dass Sie das Spitzenlimit im Produktivbetrieb wiederentdecken.