Sign inGet Started

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

VeldAltijd aanwezigBeschrijving
typeJaGrove categorie voor grove branching: een gesloten enum (auth_error, validation_error, rate_limit_error, ...).
codeJaOpaque, stabiele identifier die overeenkomt met E\d{5}. Uniek, wordt nooit hernoemd en nooit hergebruikt; de canonieke waarde om op te matchen.
nameJaLeesbare slug (ValidationError) voor leesbaarheid in logs. Altijd gecombineerd met code, nooit een vervanging ervoor.
messageJaLeesbare beschrijving. Niet stabiel; toon of log deze waarde, maar parse hem nooit.
doc_urlJaStabiele link naar de documentatiepagina voor deze code.
request_idJaCorrelatie-ID, ook geretourneerd als de X-Request-Id-responseheader. Vermeld deze in supportverzoeken.
paramNeeHet foutieve veld, wanneer één enkel veld de oorzaak is.
detailsNeeValidatiefouten per veld als {param, message}-objecten, waarbij param een pad met punten is zoals to[0].email. Alleen aanwezig bij validation_error-responses.
vendor_codeNeeLetterlijke 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.
StatustypeBetekenis
400bad_request_errorHet verzoek was ongeldig: een niet-parseerbare body of een ongeldige header (bijvoorbeeld een foute Idempotency-Key).
401auth_errorHet verzoek bevatte ontbrekende, ongeldige of ingetrokken inloggegevens. Zie Authenticatie.
402billing_errorHet verzoek vereist een betaalmethode, saldo of abonnement dat de organisatie niet heeft. Zie Facturering en gebruik.
403permission_errorDe inloggegevens zijn geldig, maar niet gemachtigd om dit verzoek uit te voeren. Zie Authenticatie.
404not_found_errorGeen route komt overeen met dit pad, of de resource bestaat niet in deze werkruimte. Zie Regio's.
409conflict_errorHet verzoek conflicteert met de huidige status van de resource, inclusief idempotentieconflicten (E01004, E01005). Zie Idempotentie.
410gone_errorDe resource bestond, maar is permanent verwijderd.
412precondition_errorEen voorwaarde voor dit verzoek is niet vervuld.
413payload_too_large_errorDe body van het verzoek overschrijdt de maximaal toegestane grootte.
421misdirected_errorHet verzoek bereikte een regio die het niet kan afhandelen. Zie Regio's.
422delivery_errorHet bericht is geaccepteerd als verzoek, maar kan niet worden bezorgd op het opgegeven adres.
422validation_errorDe body van het verzoek is geparsed, maar een of meer waarden zijn ongeldig.
425too_early_errorHet verzoek is eerder binnengekomen dan het verwerkt kan worden.
429rate_limit_errorEen rate-limitgroep is uitgeput voor deze werkruimte. Zie Rate limits.
499client_closed_request_errorDe verbinding werd gesloten voordat het antwoord klaar was, meestal omdat de aanroeper niet langer wachtte.
500internal_errorEr ging iets mis aan onze kant bij het verwerken van het verzoek. Zie Idempotency.
501not_implemented_errorHet endpoint is gedeclareerd in de API, maar nog niet geïmplementeerd.
503service_unavailable_errorIets 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;
}

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.
ReeksGebiedCodes
E01xxxInfrastructuur30 codes, 2 buiten gebruik
E02xxxAuth & identiteit9 codes, 2 buiten gebruik
E03xxxFacturering & abonnementen12 codes
E04xxxE-mailverzending & -bezorging67 codes, 3 buiten gebruik
E05xxxDomeinen & DNS19 codes
E06xxxWebhooks7 codes
E07xxxWallet4 codes
E10xxxQuota's9 codes, 2 buiten gebruik
E11xxxIP-pools & dedicated IP's4 codes, 1 buiten gebruik
E12xxxSMS-verzending & -bezorging49 codes, 5 buiten gebruik
E13xxxVerify7 codes, 1 buiten gebruik
E14xxxNummers5 codes
E15xxxWhatsApp-verzending & -bezorging49 codes
E16xxxTrust1 code
E17xxxAgent-mailboxen14 codes, 2 buiten gebruik
E19xxxRegistratiecompliance4 codes
E21xxxVoice & SIP-trunking16 codes, 7 buiten gebruik
E22xxxNummeropzoeking4 codes
E23xxxRealtime1 code
E24xxxCompetitive Insights6 codes
E25xxxSendability5 codes, 1 buiten gebruik
E27xxxInbox Insights5 codes
E28xxxApple Messages for Business18 codes, 2 buiten gebruik
E32xxxBewerkingsbevestiging6 codes

Gerelateerd

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Ontvang een implementatieoverzicht