Ratenbegrenzungen

Wie die Begrenzung funktioniert

Anfragen werden über ein gleitendes Ein-Minuten-Fenster ratenbegrenzt. Integrationen — API-Schlüssel und Tokens aus POST /api/v1/auth/login — werden je Organisation begrenzt: Ihr Kontingent pro Minute wird durch Ihren Tarif festgelegt, und alle Schlüssel einer Organisation teilen sich dasselbe Fenster. Sandbox-Verkehr wird in einem separaten Topf gemessen, sodass das Erkunden der API nie Ihr Produktionskontingent aufbraucht.

Wer in den Apps von PIE arbeitet, wird anders begrenzt, weil schon eine einzelne Seite viele Anfragen auslöst: Jede angemeldete Person hat ein eigenes Kontingent von 600 Anfragen pro Minute, und alle angemeldeten Personen einer Organisation zusammen dürfen bis zum Fünffachen des Tarifkontingents nutzen. Browser-Sitzungen verbrauchen daher nie das Kontingent, auf das Ihre Integrationen angewiesen sind.

Anmeldeversuche werden gesondert begrenzt und zählen nur Fehlversuche: zehn fehlgeschlagene Versuche für ein Konto von einer IP-Adresse oder fünfzig von einer IP-Adresse über mehrere Konten hinweg, jeweils innerhalb von 15 Minuten. Erfolgreiche Anmeldungen zählen nie.

Antwortheader

Jede Antwort meldet Ihren aktuellen Stand:

• X-RateLimit-Limit — die maximal im Fenster erlaubten Anfragen.
• X-RateLimit-Remaining — im aktuellen Fenster noch verfügbare Anfragen.
• Retry-After — nur bei einem 429 gesendet; die Anzahl der Sekunden, die vor einem erneuten Versuch zu warten ist.

429 Too Many Requests behandeln

Wenn Sie das Limit überschreiten, antwortet PIE mit 429, der Standard-Fehlerhülle und einem Retry-After-Header:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests" } }

Warten Sie vor dem erneuten Versuch mindestens Retry-After Sekunden. Ein robuster Client berücksichtigt den Header und fügt Jitter hinzu, um einen synchronisierten Retry-Sturm zu vermeiden:

async function call(url, key) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, { headers: { "X-API-Key": key } });
    if (res.status !== 429) return res;

    const wait = Number(res.headers.get("Retry-After") ?? 1);
    await sleep((wait + Math.random()) * 1000);
  }
}