Ratenbegrenzungen und Serverfehler behandeln

Eine 429-Antwort behandeln

Eine begrenzte Anfrage erhält 429 Too Many Requests mit rate_limit_exceeded in detail.status. Lesen Sie vor einer Wiederholung die Antwort-Header:

• Retry-After nennt die Mindestwartezeit in Sekunden.
• X-RateLimit-Limit nennt das Bucket-Limit.
• X-RateLimit-Remaining nennt verbleibende Anfragen.
• X-RateLimit-Reset nennt den Zeitpunkt der Bucket-Zurücksetzung.

Warten Sie gemäß Retry-After und wiederholen Sie mit exponentiellem Backoff und Zufallsstreuung. Reduzieren Sie parallele Anfragen und stellen Sie Arbeit in eine Warteschlange, statt beim Zurücksetzen des Fensters sofort eine Anfragewelle zu senden.

Serverfehler behandeln

Bei 500 enthält der öffentliche Antwortkörper einen allgemeinen Fehler und eine request_id, jedoch keine internen Ausnahme-Details. 503 kann bedeuten, dass ein notwendiger Dienst vorübergehend nicht verfügbar ist.

Wiederholen Sie reine Leseanfragen mit begrenztem Backoff. Prüfen Sie vor einer erneuten Erstellung, Änderung, Zahlung oder anderen zustandsändernden Anfrage, ob der erste Versuch abgeschlossen wurde. Ein Timeout oder 5xx beweist nicht, dass die Änderung gescheitert ist; sofortiges Wiederholen kann Arbeit duplizieren.

Diagnosedaten sichern

Notieren Sie Zeitstempel, Methode, Pfad, Status, Antwortkörper und X-Request-Id. Protokollieren Sie niemals den Wert von x-api-key. Beenden Sie automatische Wiederholungen nach wenigen begrenzten Versuchen und legen Sie den Fehler zur Prüfung vor.