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.
| Antwort | Standardaktion |
|---|---|
429, E01003 | Auf Retry-After warten, dann erneut versuchen. |
500, 502, 503 oder 504 | Lesevorgänge mit begrenztem Backoff erneut versuchen; Schreibvorgänge folgen ihrem Idempotenzvertrag. |
501 | Stoppen und prüfen, welche Operation der Server unterstützt. |
401 oder 403 | Zugangsdaten oder deren Berechtigungen korrigieren, bevor Sie es erneut versuchen. |
| Feldvalidierung oder ungültige Eingabe | Die in der Antwort angegebenen Felder korrigieren. |
409, E01004 | Auf den Abschluss der laufenden Operation warten, bevor Sie es erneut versuchen. |
409, E01005 | Die Wiederverwendung eines Idempotenzschlüssels mit abweichender Eingabe korrigieren. |
Die Idempotenzgarantie stellt sicher, dass übereinstimmende Wiederholungen innerhalb von drei Stunden genau einmal angenommen werden. Versuchen Sie einen Schreibvorgang mit demselben Schlüssel und einem identischen Request erneut und begrenzen Sie dabei das Backoff. Nach einem Timeout oder Serverfehler ist unklar, ob der Request angenommen wurde. Ein neuer Schlüssel erzeugt eine separate Operation. Wenn die erneuten Versuche ausgeschöpft sind oder die Aufbewahrungsfrist abgelaufen ist, behandeln Sie das Ergebnis als ungeklärt, bis Sie es abgeglichen haben.
Stoppen Sie, wenn das Budget für erneute Versuche erschöpft ist, und protokollieren Sie den letzten Fehler. Wenn Sie einen unveränderten Request unbegrenzt erneut versuchen, kann das 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 mir die Antwort sagen, wie ich den Fehler behebe?
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, wo es sinnvoll ist, eine bekannte statusbasierte Strategie an, um den Request erneut zu versuchen. Andernfalls stoppen Sie und protokollieren den Code mit seiner Request-ID zur Untersuchung.
Der Fehler-Leitfaden dokumentiert die Fehlerantwort. Die Fehlerreferenz listet einzelne Codes und ihre Wiederherstellungshinweise auf.
Kurz gesagt
Codes statt Meldungen abgleichen.
Bird benennt Fehlercodes nie um und verwendet sie nie erneut, aber menschenlesbare Meldungen können sich ändern.
Temporäre Fehler mit Limit erneut versuchen.
Warten Sie bei Begrenzung der Anfragerate und erhöhen Sie die Wartezeit bei temporären Serverfehlern. Verwenden Sie innerhalb des dreistündigen Idempotenzfensters denselben Schlüssel und einen identischen Request.
Validierungsdetails lesen.
E01001liefert Feldprobleme indetails. Verwenden Sie jedenparam, um die zugehörige Meldung dem betroffenen Eingabefeld zuzuordnen.Fallback für unbekannte Fehler bereithalten.
Protokollieren Sie unbekannte Codes und ihre Request-IDs, damit neue Fehler Ihren Handler nicht zum Absturz bringen.