Fouten

Elk mislukt Bird API-verzoek retourneert hetzelfde JSON-foutantwoord, genest onder een error-sleutel op het hoogste niveau. Dit is een echte respons op een verzendverzoek met een lege body:

Codevoorbeeld

{
  "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'" }]
  }
}

De HTTP-status volgt uit de type. Clientfouten gebruiken 400 voor misvormde verzoeken, 401 of 403 voor toegangsfouten, 402 voor facturering en 404 voor ontbrekende resources. Ze gebruiken 409 voor conflicten, 412 voor niet-vervulde precondities, 422 voor validatie- en bedrijfsregelfouten en 429 voor beperking van het aantal verzoeken. Bird-zijde fouten gebruiken 5xx. De status identificeert de categorie; het foutantwoord legt uit wat er is gebeurd.

De velden van het foutantwoord

Veld	Rol
type	Grove categorie voor globale vertakking: validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error en een handvol andere. Een gesloten enum die zelden groeit.
code	Opaque, stabiele identifier (E01001). De canonieke referentie: uniek, nooit hernoemd, nooit hergebruikt. Wanneer een fout wordt uitgefaseerd, wordt de code permanent gereserveerd.
name	Leesbare slug (ValidationError) voor leesbaarheid in logs. Altijd gekoppeld aan code, nooit een vervanging ervoor.
message	Leesbare beschrijving. Niet stabiel: de formulering verandert zonder waarschuwing. Toon het, log het, parseer het nooit.
param	Bij invoergerelateerde fouten het betreffende veld. Weggelaten wanneer niet van toepassing.
doc_url	Stabiele link naar de documentatiepagina voor deze code.
request_id	Altijd aanwezig, en ook geretourneerd als de X-Request-Id-responsheader. Vermeld het in supportverzoeken; hiermee kan Bird het exacte verzoek traceren.
details	Validatieproblemen per veld. Alleen aanwezig bij validation_error-responsen.
remediation	Een leesbare volgende stap om de fout op te lossen. Aanwezig wanneer een herstelactie bekend is.
next	Bewerkingen die de fout oplossen, in de volgorde waarin je ze moet proberen. Aanwezig bij fouten met een duidelijk herstelpad, zoals niet-vervulde precondities.
vendor_code	Letterlijke code van een downstream systeem (een SMTP-responscode, een betalingsweigeringscode). Alleen aanwezig wanneer Bird een code van een extern systeem doorgeeft waarop je mogelijk wilt reageren.

Vertakt op type voor grove afhandeling en op code voor specifieke afhandeling, nooit op message. Een typische client schakelt op type (opnieuw proberen bij rate_limit_error, validation_error tonen aan de gebruiker, iemand waarschuwen bij internal_error) en matcht alleen individuele code-waarden voor de paar fouten die specifiek worden afgehandeld.

Codes zoals E04012 zijn bewust opaque. Elke code linkt via doc_url naar een documentatiepagina die de oorzaak en oplossing beschrijft. De volledige catalogus staat in de foutreferentie.

Validatiefouten: één code, veel details

Validatie op veldniveau krijgt geen aparte code per veld-en-foutcombinatie. Elke validatiefout is E01001 ValidationError met een details-array die elk probleem op veldniveau als {param, message} vermeldt, op dezelfde manier als het vastgelegde mislukte verzendverzoek zijn ontbrekende eigenschappen toont. De message-strings in details kunnen veranderen en mogen alleen worden weergegeven. Gebruik param om problemen aan formuliervelden te koppelen.

Herstelbegeleiding: herstelacties en volgende stappen

Fouten met een bekende oplossing bevatten die in het foutantwoord. Dit is een echte respons op een webhooks-aanroep met een API-sleutel die de vereiste scope mist:

Codevoorbeeld

{
  "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 is een zin voor een mens of een agentlog; next bevat, indien aanwezig, de API-bewerkingen die de fout oplossen in de volgorde waarin je ze moet proberen (verifieer een domein en probeer het verzenden opnieuw). Agents en CLI's kunnen next direct uitvoeren; interactieve clients kunnen remediation ongewijzigd tonen.

Fouten goed afhandelen

Probeer 429 en 5xx standaard opnieuw, niets anders. Respecteer Retry-After bij beperking van het aantal verzoeken (zie Beperking van het aantal verzoeken), gebruik exponentiële backoff bij 5xx en stuur een Idempotency-Key zodat herhaalde muterende verzoeken veilig zijn.
Log code, name en request_id samen. De code is waarnaar je in de documentatie en je eigen logs zoekt; het request-ID is wat support nodig heeft.
Tolereer nieuwe codes en typen. Nieuwe foutcodes verschijnen regelmatig naarmate producten groeien, en de type-enum krijgt af en toe een nieuwe waarde. Schrijf je handler met een verstandige default-tak in plaats van een uitputtende match.

Volgende stappen

Foutreferentie: de volledige foutcatalogus, één pagina per code
Idempotentie: veilig opnieuw proberen bij muterende verzoeken
Beperking van het aantal verzoeken: limietheaders en backoff-begeleiding

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 integration ImplementatiegidsSend your first email

Ontvang een implementatieoverzicht