Fehler

Jede fehlgeschlagene Bird-API-Anfrage gibt dieselbe JSON-Fehlerantwort zurück, verschachtelt unter einem error-Schlüssel auf oberster Ebene. Dies ist eine echte Antwort auf eine Sendeanfrage mit leerem Body:

Codebeispiel

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

Der HTTP-Status ergibt sich aus dem type. Client-Fehler verwenden 400 für fehlerhafte Anfragen, 401 oder 403 für Zugriffsfehler, 402 für Abrechnungsprobleme und 404 für fehlende Ressourcen. Sie verwenden 409 für Konflikte, 412 für nicht erfüllte Vorbedingungen, 422 für Validierungs- und Geschäftsregelverstöße und 429 für die Begrenzung der Anfragerate. Fehler auf Bird-Seite verwenden 5xx. Der Status benennt die Kategorie; die Fehlerantwort erklärt, was passiert ist.

Die Felder der Fehlerantwort

Feld	Rolle
type	Grobe Kategorie für einfache Verzweigung: validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error und einige weitere. Ein geschlossenes Enum, das selten erweitert wird.
code	Opaker, stabiler Bezeichner (E01001). Die kanonische Referenz: eindeutig, wird nie umbenannt und nie wiederverwendet. Wenn ein Fehler außer Dienst gestellt wird, bleibt sein Code dauerhaft reserviert.
name	Menschenlesbarer Slug (ValidationError) für die Lesbarkeit in Logs. Immer zusammen mit code, nie als Ersatz dafür.
message	Menschenlesbare Beschreibung. Nicht stabil: Der Wortlaut kann sich ohne Vorankündigung ändern. Anzeigen und loggen, aber nie parsen.
param	Bei eingabebezogenen Fehlern das betroffene Feld. Wird weggelassen, wenn nicht zutreffend.
doc_url	Stabiler Link zur Dokumentationsseite dieses Codes.
request_id	Immer vorhanden und wird auch als X-Request-Id-Response-Header zurückgegeben. Geben Sie sie in Support-Anfragen an; damit kann Bird die genaue Anfrage nachverfolgen.
details	Validierungsprobleme auf Feldebene. Nur bei validation_error-Antworten vorhanden.
remediation	Ein menschenlesbarer nächster Schritt zur Behebung des Fehlers. Vorhanden, wenn eine Lösung bekannt ist.
next	Operationen, die den Fehler beheben, in der Reihenfolge, in der Sie sie ausprobieren sollten. Vorhanden bei Fehlern mit klar definierter Lösung, z. B. nicht erfüllten Vorbedingungen.
vendor_code	Originalcode eines nachgelagerten Systems (ein SMTP-Antwortcode, ein Zahlungsablehnungscode). Nur vorhanden, wenn Bird den Code eines externen Systems weitergibt, auf den Sie reagieren möchten.

Verzweigen Sie auf type für grobe Behandlung und auf code für spezifische Behandlung, nie auf message. Ein typischer Client verzweigt auf type (erneut versuchen bei rate_limit_error, validation_error dem Benutzer anzeigen, bei internal_error jemanden alarmieren) und prüft einzelne code-Werte nur für die wenigen Fehler, die er gesondert behandelt.

Codes wie E04012 sind absichtlich opak. Jeder Code verlinkt über doc_url auf eine Dokumentationsseite, die Ursache und Lösung erklärt. Der vollständige Katalog befindet sich in der Fehlerreferenz.

Validierungsfehler: ein Code, viele Details

Validierung auf Feldebene erhält keinen eigenen Code pro Feld-Fehler-Kombination. Jeder Validierungsfehler ist E01001 ValidationError mit einem details-Array, das jedes Problem auf Feldebene als {param, message} auflistet – so wie der erfasste Sendefehler seine fehlenden Eigenschaften auflistet. Die message-Strings in details können sich ändern und sollten nur angezeigt werden. Verwenden Sie param, um Probleme Formularfeldern zuzuordnen.

Hinweise zur Behebung: Remediation und Next

Fehler mit bekannter Lösung liefern diese in der Fehlerantwort mit. Dies ist eine echte Antwort auf einen Webhooks-Aufruf mit einem API-Key, dem der erforderliche Scope fehlt:

Codebeispiel

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation ist ein Satz für einen Menschen oder ein Agent-Log; next listet, wenn vorhanden, die API-Operationen auf, die den Fehler beheben, in der Reihenfolge, in der Sie sie ausprobieren sollten (Domain verifizieren, dann den Versand erneut versuchen). Agents und CLIs können next direkt ausführen; interaktive Clients können remediation unverändert anzeigen.

Fehler richtig behandeln

Wiederholen Sie 429 und 5xx, standardmäßig nichts anderes. Beachten Sie Retry-After bei der Begrenzung der Anfragerate (siehe Begrenzung der Anfragerate), verwenden Sie exponentielles Backoff bei 5xx und senden Sie einen Idempotency-Key, damit Wiederholungen von ändernden Anfragen sicher sind.
Loggen Sie code, name und request_id zusammen. Der Code ist das, wonach Sie in der Dokumentation und Ihren eigenen Logs suchen; die Request-ID ist das, was der Support benötigt.
Tolerieren Sie neue Codes und Typen. Neue Fehlercodes werden regelmäßig mit wachsenden Produkten ausgeliefert, und das type-Enum erhält gelegentlich einen neuen Wert. Schreiben Sie Ihren Handler mit einem sinnvollen Default-Zweig statt eines vollständigen Matchings.

Nächste Schritte

Fehlerreferenz: der vollständige Fehlerkatalog, eine Seite pro Code
Idempotenz: sichere Wiederholungen für ändernde Anfragen
Begrenzung der Anfragerate: Limit-Header und Backoff-Hinweise