Was ist ein Fehlerkatalog, und wie ordne ich Fehlercodes Retry-Strategien zu?

Ein fehlgeschlagener Request kann eine Verzögerung, ein korrigiertes Feld oder andere Zugangsdaten erfordern. Die Fehlerantwort von Bird liefert Felder, mit denen Ihr Handler die passende Aktion wählen kann.

Welche Fehlerfelder sollte ich verwenden?

Verwenden Sie type für die grobe Zuordnung und code für eine gezielte Wiederherstellung. Bird platziert diese Felder in einem error-Objekt auf oberster Ebene.

Der Typ gruppiert Fehler wie Validierung, Authentifizierung und Begrenzung der Anfragerate. Der Code identifiziert den konkreten Fehler, z. B. E01001 für Feldvalidierung.

Bird benennt einen Code nie um und verwendet ihn nie erneut. Zurückgezogene Codes bleiben reserviert, sodass eine bestehende Code-Zuordnung ihre Bedeutung behält.

Zeigen Sie message an oder protokollieren Sie es, aber gleichen Sie den Text nicht ab. Der Wortlaut kann sich ändern, ohne dass sich der Fehler ändert, den Ihr Handler behandeln muss.

Das name macht Logs lesbar. Der doc_url verlinkt auf die Dokumentation des Codes. Protokollieren Sie code, name und request_id zusammen, wenn eine Operation fehlschlägt.

Welche Fehler sollte ich erneut versuchen?

Versuchen Sie temporäre Fehler mit einer begrenzten Strategie erneut. Beheben Sie Eingabe- und Zugangsprobleme, bevor Sie es erneut versuchen. Prüfen Sie den konkreten Code, wenn ein Status unterschiedliche Aktionen erfordern kann.

Verwenden Sie denselben Idempotenzschlüssel, wenn Sie denselben Schreibvorgang erneut versuchen. Ein Timeout oder Serverfehler beweist nicht, dass die ursprüngliche Operation nichts bewirkt hat.

Stoppen Sie, wenn das Retry-Budget erschöpft ist, und protokollieren Sie den letzten Fehler. Einen unveränderten Request unbegrenzt zu wiederholen kann einen Fehler verbergen, der manuelles Eingreifen erfordert.

Wie behandle ich Feldvalidierungsfehler?

Lesen Sie das details-Array in E01001 ValidationError und ordnen Sie jeden Eintrag seinem param zu. Zeigen Sie die message des Eintrags neben dem betroffenen Feld an.

Parsen Sie diese Meldungen nicht, um das Feld oder den Fehler zu identifizieren. Ihr Wortlaut kann sich ändern, genau wie die Meldung auf oberster Ebene.

Ein fehlerhaft formatierter Request kann stattdessen E01002 InvalidRequest zurückgeben. Verwenden Sie die dokumentierte Wiederherstellung, anstatt davon auszugehen, dass jeder Eingabefehler Details auf Feldebene enthält.

Kann die Antwort mir sagen, wie ich wiederherstelle?

Manche Fehler enthalten remediation, einen menschenlesbaren nächsten Schritt, oder next, eine geordnete Liste von Operationen zum Ausprobieren.

Zeigen Sie die Fehlerbehebung an, wenn sie der Person hilft, das Problem zu korrigieren. Beispielsweise kann ein Autorisierungsfehler Zugangsdaten mit einem zusätzlichen Scope erfordern.

Ein automatisierter Handler kann next verwenden, um eine Wiederherstellungsoperation auszuwählen. Er benötigt dennoch die Eingaben und Berechtigungen dieser Operation, bevor er sie ausführt.

Ein vendor_code identifiziert einen nachgelagerten Fehler, z. B. eine SMTP-Antwort oder eine Zahlungsablehnung. Konsultieren Sie den Code des jeweiligen Anbieters, wenn die Wiederherstellung davon abhängt.

Was sollte bei einem unbekannten Code passieren?

Behalten Sie einen Default-Zweig bei, der den Fehler protokolliert, ohne abzustürzen oder unbegrenzt erneut zu versuchen. Neue Codes und Typen können hinzukommen, wenn der API wächst.

Wenden Sie eine bekannte statusbasierte Retry-Strategie an, wo es sinnvoll ist. Andernfalls stoppen Sie und protokollieren Sie den Code mit seiner Request-ID zur Untersuchung.

Der Fehler-Leitfaden dokumentiert die Fehlerantwort. Die Fehlerreferenz listet einzelne Codes und ihre Wiederherstellungshinweise auf.