Ratenlimits & Fehler

Ratenlimits

Die Limits gelten pro API-Schlüssel (oder pro OAuth-Client) und Minute. Wird das Limit überschritten, folgt 429 Too Many Requests.

Brauchst du höhere Limits für deine Integration? Wende dich an unser Team.

Gleichzeitig offene Live-Sitzungen sind eine eigene Obergrenze, kein Ratenlimit: Free 1 Raum, Pro 1 pro Präsentator-Lizenz, Premium 2. Wird sie erreicht, folgt 403 mit dem Code session_limit. Beende einen Raum in Studio (oder per POST /api/v1/sessions/{id}/control mit end), bevor du einen weiteren öffnest.

Ratenlimit-Header

JSON-Antworten führen Metadaten-Header zum Ratenlimit mit:

X-RateLimit-Limit: 120
X-RateLimit-Window: 60s

Ein überschrittenes Limit liefert 429 mit dem Fehlercode rate_limited. Warte, bevor du es erneut versuchst. Einen Retry-After-Header gibt es nicht.

Format der Fehlerantwort

Alle API-Fehler liefern einen JSON-Body mit einem verschachtelten error-Objekt, das einen maschinenlesbaren code und eine lesbare message enthält:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "not_found",
    "message": "Poll not found."
  }
}

Validierungsfehler liefern 422 mit einem Feld details im Fehlerobjekt:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": {
      "fieldErrors": { "title": ["String must contain at least 1 character(s)"] },
      "formErrors": []
    }
  }
}

OAuth-Token-Fehler folgen stattdessen dem Format RFC 6749 §5.2:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

Fehlercodes

Wiederholungen & Backoff

Für Produktionsintegrationen empfehlen wir exponentielles Backoff mit Jitter:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status === 429) {
      // PollsLive does not send Retry-After, so back off exponentially
      // (capped at one minute, the length of a rate-limit window).
      const backoff = Math.min(1000 * 2 ** attempt + Math.random() * 500, 60000);
      await new Promise((r) => setTimeout(r, backoff));
      continue;
    }
    if (res.status >= 500 && attempt < maxRetries) {
      const backoff = Math.min(1000 * 2 ** attempt + Math.random() * 500, 30000);
      await new Promise((r) => setTimeout(r, backoff));
      continue;
    }
    return res;
  }
  throw new Error("Max retries exceeded");
}

Wiederhole nicht bei 4xx-Fehlern (außer 429). Sie weisen auf ein Problem in deiner Anfrage hin, das sich durch Wiederholen nicht löst.

OAuth-Fehlerformat

Der Token-Endpunkt (POST /api/oauth/token) liefert Fehler im RFC-6749-Format: