Sign inGet started

Fehlerantworten

Jede fehlgeschlagene Anfrage gibt denselben JSON-Envelope unter einem error-Schlüssel auf oberster Ebene zurück, mit einem HTTP-Status, der Ihnen die grobe Kategorie mitteilt. Diese Seite beschreibt den Wire-Vertrag; für Hinweise zu Verzweigungslogik, erneuten Versuchen und der Philosophie des Fehlerkatalogs siehe Fehler.
Codebeispiel
{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request validation failed.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg",
    "details": [
      { "param": "contact_id", "message": "this field is reserved and not yet supported" },
      { "param": "topic_id", "message": "this field is reserved and not yet supported" }
    ]
  }
}

Envelope-Felder

FeldImmer vorhandenBeschreibung
typeJaGrobe Kategorie für die Verzweigungslogik: ein geschlossenes Enum (auth_error, validation_error, rate_limit_error, …).
codeJaOpaker, stabiler Bezeichner passend zu E\d{5}. Eindeutig, wird nie umbenannt und nie wiederverwendet; der kanonische Wert für den Abgleich.
nameJaMenschenlesbarer Slug (ValidationError) für die Lesbarkeit in Logs. Immer zusammen mit code, nie als Ersatz dafür.
messageJaMenschenlesbare Beschreibung. Nicht stabil; anzeigen oder loggen, nie parsen.
doc_urlJaStabiler Link zur Dokumentationsseite für diesen code.
request_idJaKorrelations-ID, wird auch als X-Request-Id-Response-Header zurückgegeben. Geben Sie sie in Supportanfragen an.
paramNeinDas fehlerhafte Feld, wenn ein einzelnes Feld die Ursache ist.
detailsNeinFeldweise Validierungsfehler als {param, message}-Objekte, wobei param ein Pfad mit Punktnotation wie to[0].email ist. Nur bei validation_error-Antworten vorhanden.
vendor_codeNeinWörtlicher Code aus einem nachgelagerten System (ein SMTP-Antwortcode, ein Zahlungsablehnungscode), wenn er handlungsrelevant ist.

HTTP-Statusmapping

Jeder type ist genau einem HTTP-Status zugeordnet, sodass Status und Envelope nie voneinander abweichen.
StatustypeBedeutung
400bad_request_errorDie Anfrage war fehlerhaft: ein nicht parsbarer Body oder ein ungültiger Header (zum Beispiel ein fehlerhafter Idempotency-Key).
401auth_errorDie Anfrage enthielt fehlende, ungültige oder widerrufene Zugangsdaten. Siehe Authentifizierung.
402billing_errorDie Anfrage erfordert eine Zahlungsmethode, ein Guthaben oder einen Plan, über den die Organisation nicht verfügt. Siehe Abrechnung und Nutzung.
403permission_errorDie Zugangsdaten sind gültig, aber nicht berechtigt, diese Anfrage auszuführen. Siehe Authentifizierung.
404not_found_errorKeine Route passt zu diesem Pfad, oder die Ressource existiert in diesem Workspace nicht. Siehe Regionen.
409conflict_errorDie Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource, einschließlich Idempotenz-Konflikten (E01004, E01005). Siehe Idempotenz.
410gone_errorDie Ressource existierte, wurde aber dauerhaft entfernt.
412precondition_errorEine Vorbedingung für diese Anfrage wurde nicht erfüllt.
413payload_too_large_errorDer Anfrage-Body überschreitet die maximal zulässige Größe.
421misdirected_errorDie Anfrage hat eine Region erreicht, die sie nicht bedienen kann. Siehe Regionen.
422delivery_errorDie Nachricht wurde als Anfrage angenommen, kann aber nicht wie adressiert zugestellt werden.
422validation_errorDer Anfrage-Body wurde geparst, aber ein oder mehrere Werte sind ungültig.
425too_early_errorDie Anfrage ist früher eingetroffen, als sie verarbeitet werden kann.
429rate_limit_errorEine Rate-Limit-Gruppe ist für diesen Workspace erschöpft. Siehe Begrenzung der Anfragerate.
500internal_errorAuf unserer Seite ist bei der Verarbeitung der Anfrage ein Fehler aufgetreten. Siehe Idempotenz.
501not_implemented_errorDer Endpunkt ist in der API deklariert, aber noch nicht implementiert.
503service_unavailable_errorEtwas, von dem diese Anfrage abhängt, ist vorübergehend nicht verfügbar.

Fehlerbehandlung in den SDKs

Jedes SDK bildet den Envelope auf das native Fehlermodell seiner Sprache ab und trägt alle Envelope-Felder (type, code, message, doc_url, request_id, …) am Fehlerwert.
import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

Fehlerkatalog

Alle Fehlercodes, die die öffentliche Bird API zurückgibt, aufgeteilt auf eine Seite pro Codebereich. Jede Bereichsseite listet ihre Codes auf, und jeder Code hat eine eigene Seite mit Ursache und Handlungsempfehlung. Der doc_url in jeder Fehlerantwort verlinkt direkt auf die Seite dieses Codes.
BereichGebietCodes
E01xxxInfrastruktur27 Codes
E02xxxAuth & Identität8 Codes, 2 außer Dienst
E03xxxAbrechnung & Pläne11 Codes
E04xxxE-Mail-Versand & -Zustellung41 Codes, 2 außer Dienst
E05xxxDomains & DNS19 Codes
E06xxxWebhooks6 Codes
E07xxxWallet3 Codes
E10xxxKontingente4 Codes, 2 außer Dienst
E11xxxIP-Pools & dedizierte IPs4 Codes, 1 außer Dienst
E12xxxSMS-Versand & -Zustellung43 Codes, 5 außer Dienst
E13xxxVerify7 Codes, 1 außer Dienst
E14xxxNummern5 Codes
E15xxxWhatsApp-Versand & -Zustellung32 Codes
E16xxxTrust1 Code
E17xxxAgenten-Postfächer14 Codes, 2 außer Dienst
E19xxxRegistrierungs-Compliance4 Codes
E21xxxVoice & SIP-Trunking1 Code, 3 außer Dienst
E22xxxNummernauskunft4 Codes
E23xxxRealtime1 Code
E25xxxSendability5 Codes, 1 außer Dienst
E28xxxApple Messages for Business2 Codes, 2 außer Dienst

Weiterführend