Fehler und Rate-Limits zuverlässig behandeln

Entwicklerhandbuch · Zuletzt aktualisiert am 16.08.2026

Auf dieser Seite

Immer den Fehlercode auswerten
Entscheidung je Fehlerklasse
401 und 403 nicht verwechseln
Rate-Limit vor dem Fehler erkennen
Wiederholungen mit Backoff
Lokale Daten bei Störungen behalten
Antworten vor der Verarbeitung validieren

Ein stabiler Client unterscheidet dauerhafte Konfigurationsfehler von vorübergehenden Störungen. Wiederhole nicht jeden fehlgeschlagenen Aufruf blind: Bei manchen Fehlern hilft Warten, bei anderen nur eine Änderung der Konfiguration.

Immer den Fehlercode auswerten#

Fehler verwenden denselben Umschlag wie erfolgreiche Antworten:

{
  "data": null,
  "meta": null,
  "errors": [
    { "status": 403, "code": "entitlement_paused", "message": "…" }
  ]
}

Verzweige über errors[0].code. message ist für Menschen geschrieben und kann sprachlich überarbeitet werden.

Entscheidung je Fehlerklasse#

Code	Reaktion des Clients
`invalid_token`	Abrufe stoppen und ein neues Token hinterlegen. Automatische Wiederholungen helfen nicht.
`entitlement_paused`	Lokalen Bestand nicht als Authentifizierungsfehler behandeln. Tarif oder aktive Auswahl prüfen.
`feed_not_found`	Feed-UUID und freigegebenen Umfang prüfen.
`post_not_found`	Lokale Detailansicht entfernen oder neu über die Feed-Liste abgleichen.
`invalid_parameter`	Anfrage korrigieren. Die Meldung nennt den unlesbaren Parameter.
`rate_limited`	`Retry-After` abwarten und danach erneut versuchen.
`server_error`	Lokalen Bestand behalten und mit wachsendem Abstand wiederholen.

Unbekannte künftige Codes behandelst du zunächst anhand des HTTP-Status.

401 und 403 nicht verwechseln#

401 invalid_token bedeutet, dass das Token fehlt oder nicht mehr gültig ist. 403 entitlement_paused bedeutet dagegen, dass das Token korrekt ist, die Verknüpfung oder der Feed aber gerade nicht ausgeliefert wird.

Erzeuge bei 403 kein neues Token. Sobald der Umfang wieder aktiv ist, kann dasselbe Token weiterverwendet werden.

Rate-Limit vor dem Fehler erkennen#

Jede reguläre API-Antwort trägt:

X-RateLimit-Limit: Gesamtbudget im aktuellen Minutenfenster
X-RateLimit-Remaining: verbleibende Anfragen
X-RateLimit-Reset: Unix-Zeitpunkt des nächsten Fensters

Für API-Verknüpfungen gelten 300 Anfragen pro Minute in Pro und 600 in Business. Ein 429 enthält zusätzlich Retry-After in Sekunden.

const retryAfter = Number(response.headers.get('retry-after') || 0);
if (response.status === 429) {
  scheduleRetry(Math.max(retryAfter, 1));
}

ETags reduzieren unnötige Nutzlast, zählen aber weiterhin als Anfrage. Plane das Abrufintervall deshalb unabhängig von der Antwortgröße.

Wiederholungen mit Backoff#

Für Netzwerkfehler, Zeitüberschreitungen, 408, 429 und 5xx eignet sich ein wachsender Abstand mit einem kleinen Zufallsanteil:

1. Versuch: nach 5 Sekunden
2. Versuch: nach 15 Sekunden
3. Versuch: nach 45 Sekunden
weitere Versuche: begrenzt bis zum nächsten regulären Lauf

Bei 429 hat Retry-After Vorrang. Vermeide parallele Wiederholungsstürme, wenn mehrere Feeds gleichzeitig fehlschlagen.

Lokale Daten bei Störungen behalten#

Entferne niemals Posts oder Feeds aufgrund von:

DNS- oder Verbindungsfehlern
Zeitüberschreitungen
5xx-Antworten
HTML statt JSON
einem JSON-Objekt ohne erwartete Felder
einer abgebrochenen Cursor-Kette

Nur eine vollständig validierte API-Antwort ist eine Aussage über den aktuellen Feed. Das gilt besonders für Vollabgleiche, die lokale Inhalte entfernen dürfen.

Antworten vor der Verarbeitung validieren#

Prüfe mindestens:

Antwort ist JSON-Objekt
data, meta und errors sind vorhanden
bei Erfolg: errors ist leer
bei Post-Listen: data ist Array
bei Post-Listen: meta.pagination.next_cursor ist vorhanden
next_cursor ist null oder nichtleerer String

Die vollständige Fehler- und Header-Referenz findest du unter Fehlercodes und Rate-Limits.

Frage nicht beantwortet? Schreib uns — wir ergänzen die Seite.

Hilfe-Themen