Foutantwoorden
Elk mislukt verzoek retourneert dezelfde JSON-envelop onder een top-level error-sleutel, met een HTTP-status die de grove categorie aangeeft. Deze pagina is het wire-contract; voor richtlijnen over branching, opnieuw proberen en de filosofie achter de foutcodecatalogus, zie Fouten.
Codevoorbeeld
{
"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" }
]
}
}Envelopvelden
| Veld | Altijd aanwezig | Beschrijving |
|---|---|---|
| type | Ja | Grove categorie voor grove branching: een gesloten enum (auth_error, validation_error, rate_limit_error, ...). |
| code | Ja | Opaque, stabiele identifier die overeenkomt met E\d{5}. Uniek, wordt nooit hernoemd en nooit hergebruikt; de canonieke waarde om op te matchen. |
| name | Ja | Leesbare slug (ValidationError) voor leesbaarheid in logs. Altijd gecombineerd met code, nooit een vervanging ervoor. |
| message | Ja | Leesbare beschrijving. Niet stabiel; toon of log deze waarde, maar parse hem nooit. |
| doc_url | Ja | Stabiele link naar de documentatiepagina voor deze code. |
| request_id | Ja | Correlatie-ID, ook geretourneerd als de X-Request-Id-responseheader. Vermeld deze in supportverzoeken. |
| param | Nee | Het foutieve veld, wanneer één enkel veld de oorzaak is. |
| details | Nee | Validatiefouten per veld als {param, message}-objecten, waarbij param een pad met punten is zoals to[0].email. Alleen aanwezig bij validation_error-responses. |
| vendor_code | Nee | Letterlijke code van een downstream-systeem (een SMTP-antwoordcode, een betaalweigeringscode) wanneer er actie op ondernomen kan worden. |
HTTP-statusmapping
Elke type verwijst naar precies één HTTP-status, zodat de status en de envelop nooit van elkaar afwijken.
| Status | type | Betekenis |
|---|---|---|
| 400 | bad_request_error | Het verzoek was ongeldig: een niet-parseerbare body of een ongeldige header (bijvoorbeeld een foute Idempotency-Key). |
| 401 | auth_error | Het verzoek bevatte ontbrekende, ongeldige of ingetrokken inloggegevens. Zie Authenticatie. |
| 402 | billing_error | Het verzoek vereist een betaalmethode, saldo of abonnement dat de organisatie niet heeft. Zie Facturering en gebruik. |
| 403 | permission_error | De inloggegevens zijn geldig, maar niet gemachtigd om dit verzoek uit te voeren. Zie Authenticatie. |
| 404 | not_found_error | Geen route komt overeen met dit pad, of de resource bestaat niet in deze werkruimte. Zie Regio's. |
| 409 | conflict_error | Het verzoek conflicteert met de huidige status van de resource, inclusief idempotentieconflicten (E01004, E01005). Zie Idempotentie. |
| 410 | gone_error | De resource bestond, maar is permanent verwijderd. |
| 412 | precondition_error | Een voorwaarde voor dit verzoek is niet vervuld. |
| 413 | payload_too_large_error | De body van het verzoek overschrijdt de maximaal toegestane grootte. |
| 421 | misdirected_error | Het verzoek bereikte een regio die het niet kan afhandelen. Zie Regio's. |
| 422 | delivery_error | Het bericht is geaccepteerd als verzoek, maar kan niet worden bezorgd op het opgegeven adres. |
| 422 | validation_error | De body van het verzoek is geparsed, maar een of meer waarden zijn ongeldig. |
| 425 | too_early_error | Het verzoek is eerder binnengekomen dan het verwerkt kan worden. |
| 429 | rate_limit_error | Een rate-limitgroep is uitgeput voor deze werkruimte. Zie Rate limits. |
| 499 | client_closed_request_error | De verbinding werd gesloten voordat het antwoord klaar was, meestal omdat de aanroeper niet langer wachtte. |
| 500 | internal_error | Er ging iets mis aan onze kant bij het verwerken van het verzoek. Zie Idempotency. |
| 501 | not_implemented_error | Het endpoint is gedeclareerd in de API, maar nog niet geïmplementeerd. |
| 503 | service_unavailable_error | Iets waar dit verzoek van afhankelijk is, is tijdelijk niet beschikbaar. |
Fouten afhandelen in de SDK's
Elke SDK mapt de envelop naar het native foutmodel van de betreffende taal en bevat elk envelopveld (type, code, message, doc_url, request_id, ...) op de foutwaarde.
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();
}Foutcodecatalogus
Elke foutcode die de publieke Bird API retourneert, opgesplitst in één pagina per codereeks. Elke reekspagina toont de bijbehorende codes, en elke code heeft een eigen pagina met de oorzaak en wat je moet doen. De doc_url in elk foutantwoord linkt rechtstreeks naar de pagina van die code.
| Reeks | Gebied | Codes |
|---|---|---|
| E01xxx | Infrastructuur | 30 codes, 2 buiten gebruik |
| E02xxx | Auth & identiteit | 9 codes, 2 buiten gebruik |
| E03xxx | Facturering & abonnementen | 12 codes |
| E04xxx | E-mailverzending & -bezorging | 67 codes, 3 buiten gebruik |
| E05xxx | Domeinen & DNS | 19 codes |
| E06xxx | Webhooks | 7 codes |
| E07xxx | Wallet | 4 codes |
| E10xxx | Quota's | 9 codes, 2 buiten gebruik |
| E11xxx | IP-pools & dedicated IP's | 4 codes, 1 buiten gebruik |
| E12xxx | SMS-verzending & -bezorging | 49 codes, 5 buiten gebruik |
| E13xxx | Verify | 7 codes, 1 buiten gebruik |
| E14xxx | Nummers | 5 codes |
| E15xxx | WhatsApp-verzending & -bezorging | 49 codes |
| E16xxx | Trust | 1 code |
| E17xxx | Agent-mailboxen | 14 codes, 2 buiten gebruik |
| E19xxx | Registratiecompliance | 4 codes |
| E21xxx | Voice & SIP-trunking | 16 codes, 7 buiten gebruik |
| E22xxx | Nummeropzoeking | 4 codes |
| E23xxx | Realtime | 1 code |
| E24xxx | Competitive Insights | 6 codes |
| E25xxx | Sendability | 5 codes, 1 buiten gebruik |
| E27xxx | Inbox Insights | 5 codes |
| E28xxx | Apple Messages for Business | 18 codes, 2 buiten gebruik |
| E32xxx | Bewerkingsbevestiging | 6 codes |
Gerelateerd
- Foutconcepten: branchingstrategie, validatiedetails en vendor_code-semantiek
- Authenticatie: inloggegevens achter 401 en 403
- Idempotency-Key-header: de 409-conflictfouten en veilig opnieuw proberen
- Limieten voor het aantal verzoeken: beleid, headers en omgaan met 429
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integrationImplementatiegidsSend your first email
Ontvang een implementatieoverzicht