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
| Feld | Immer vorhanden | Beschreibung |
|---|---|---|
| type | Ja | Grobe Kategorie für die Verzweigungslogik: ein geschlossenes Enum (auth_error, validation_error, rate_limit_error, …). |
| code | Ja | Opaker, stabiler Bezeichner passend zu E\d{5}. Eindeutig, wird nie umbenannt und nie wiederverwendet; der kanonische Wert für den Abgleich. |
| name | Ja | Menschenlesbarer Slug (ValidationError) für die Lesbarkeit in Logs. Immer zusammen mit code, nie als Ersatz dafür. |
| message | Ja | Menschenlesbare Beschreibung. Nicht stabil; anzeigen oder loggen, nie parsen. |
| doc_url | Ja | Stabiler Link zur Dokumentationsseite für diesen code. |
| request_id | Ja | Korrelations-ID, wird auch als X-Request-Id-Response-Header zurückgegeben. Geben Sie sie in Supportanfragen an. |
| param | Nein | Das fehlerhafte Feld, wenn ein einzelnes Feld die Ursache ist. |
| details | Nein | Feldweise Validierungsfehler als {param, message}-Objekte, wobei param ein Pfad mit Punktnotation wie to[0].email ist. Nur bei validation_error-Antworten vorhanden. |
| vendor_code | Nein | Wö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.
| Status | type | Bedeutung |
|---|---|---|
| 400 | bad_request_error | Die Anfrage war fehlerhaft: ein nicht parsbarer Body oder ein ungültiger Header (zum Beispiel ein fehlerhafter Idempotency-Key). |
| 401 | auth_error | Die Anfrage enthielt fehlende, ungültige oder widerrufene Zugangsdaten. Siehe Authentifizierung. |
| 402 | billing_error | Die Anfrage erfordert eine Zahlungsmethode, ein Guthaben oder einen Plan, über den die Organisation nicht verfügt. Siehe Abrechnung und Nutzung. |
| 403 | permission_error | Die Zugangsdaten sind gültig, aber nicht berechtigt, diese Anfrage auszuführen. Siehe Authentifizierung. |
| 404 | not_found_error | Keine Route passt zu diesem Pfad, oder die Ressource existiert in diesem Workspace nicht. Siehe Regionen. |
| 409 | conflict_error | Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource, einschließlich Idempotenz-Konflikten (E01004, E01005). Siehe Idempotenz. |
| 410 | gone_error | Die Ressource existierte, wurde aber dauerhaft entfernt. |
| 412 | precondition_error | Eine Vorbedingung für diese Anfrage wurde nicht erfüllt. |
| 413 | payload_too_large_error | Der Anfrage-Body überschreitet die maximal zulässige Größe. |
| 421 | misdirected_error | Die Anfrage hat eine Region erreicht, die sie nicht bedienen kann. Siehe Regionen. |
| 422 | delivery_error | Die Nachricht wurde als Anfrage angenommen, kann aber nicht wie adressiert zugestellt werden. |
| 422 | validation_error | Der Anfrage-Body wurde geparst, aber ein oder mehrere Werte sind ungültig. |
| 425 | too_early_error | Die Anfrage ist früher eingetroffen, als sie verarbeitet werden kann. |
| 429 | rate_limit_error | Eine Rate-Limit-Gruppe ist für diesen Workspace erschöpft. Siehe Begrenzung der Anfragerate. |
| 500 | internal_error | Auf unserer Seite ist bei der Verarbeitung der Anfrage ein Fehler aufgetreten. Siehe Idempotenz. |
| 501 | not_implemented_error | Der Endpunkt ist in der API deklariert, aber noch nicht implementiert. |
| 503 | service_unavailable_error | Etwas, 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;
}from bird import APIStatusError, RateLimitError, ValidationError
try:
client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
text="My first Bird email.",
)
except RateLimitError as err:
print("rate limited; retry after", err.retry_after)
except ValidationError as err:
print(err.status_code, err.details)
except APIStatusError as err:
print(err.status_code, err.code, err.request_id)if err != nil {
var rle *bird.RateLimitError
var ve *bird.ValidationError
var ae *bird.APIError
switch {
case errors.As(err, &rle):
fmt.Println("rate limited; retry after", rle.RetryAfter)
case errors.As(err, &ve):
for _, d := range ve.Details {
fmt.Printf("%s: %s\n", d.Param, d.Message)
}
case errors.As(err, &ae):
fmt.Printf("API error %s (status %d, request %s)\n", ae.Code, ae.StatusCode, ae.RequestID)
default:
log.Print(err) // transport: *bird.ConnectionError or *bird.TimeoutError
}
}try {
$bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
} catch (ApiException $e) {
// The server returned an error response. $status is the HTTP status, $type
// the coarse category, $errorCode the stable E##### code.
echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
// All retry attempts failed, so no HTTP response is available.
echo 'transport error: ', $e->getMessage();
}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.
| Bereich | Gebiet | Codes |
|---|---|---|
| E01xxx | Infrastruktur | 27 Codes |
| E02xxx | Auth & Identität | 8 Codes, 2 außer Dienst |
| E03xxx | Abrechnung & Pläne | 11 Codes |
| E04xxx | E-Mail-Versand & -Zustellung | 41 Codes, 2 außer Dienst |
| E05xxx | Domains & DNS | 19 Codes |
| E06xxx | Webhooks | 6 Codes |
| E07xxx | Wallet | 3 Codes |
| E10xxx | Kontingente | 4 Codes, 2 außer Dienst |
| E11xxx | IP-Pools & dedizierte IPs | 4 Codes, 1 außer Dienst |
| E12xxx | SMS-Versand & -Zustellung | 43 Codes, 5 außer Dienst |
| E13xxx | Verify | 7 Codes, 1 außer Dienst |
| E14xxx | Nummern | 5 Codes |
| E15xxx | WhatsApp-Versand & -Zustellung | 32 Codes |
| E16xxx | Trust | 1 Code |
| E17xxx | Agenten-Postfächer | 14 Codes, 2 außer Dienst |
| E19xxx | Registrierungs-Compliance | 4 Codes |
| E21xxx | Voice & SIP-Trunking | 1 Code, 3 außer Dienst |
| E22xxx | Nummernauskunft | 4 Codes |
| E23xxx | Realtime | 1 Code |
| E25xxx | Sendability | 5 Codes, 1 außer Dienst |
| E28xxx | Apple Messages for Business | 2 Codes, 2 außer Dienst |
Weiterführend
- Fehlerkonzepte: Verzweigungsstrategie, Validierungsdetails und vendor_code-Semantik
- Authentifizierung: Zugangsdaten hinter 401 und 403
- Idempotency-Key-Header: die 409-Konfliktfehler und sichere erneute Versuche
- Begrenzung der Anfragerate: Gruppen, Header und Umgang mit 429
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Das Konzept verstehenShould I use a Bird SDK or call the API directly?Dem Lernpfad folgenBuild your first integrationImplementierungsleitfadenSend your first email
Implementierungs-Briefing erhalten