Sign inGet started

Réponses d'erreur

Chaque requête échouée renvoie la même réponse d'erreur JSON sous une clé de premier niveau error, avec un statut HTTP qui vous indique la catégorie générale. Cette page décrit le contrat filaire ; pour des conseils sur le branchement, les nouvelles tentatives et la philosophie du catalogue de codes, consultez Erreurs.
Exemple de code
{
  "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" }
    ]
  }
}

Champs de la réponse d'erreur

ChampToujours présentDescription
typeOuiCatégorie générale pour un branchement grossier : une énumération fermée (auth_error, validation_error, rate_limit_error, …).
codeOuiIdentifiant opaque et stable correspondant à E\d{5}. Unique, jamais renommé, jamais réutilisé ; la valeur canonique sur laquelle baser vos correspondances.
nameOuiSlug lisible (ValidationError) pour faciliter la lecture des logs. Toujours associé à code, jamais un substitut.
messageOuiDescription lisible. Non stable ; affichez-la ou journalisez-la, ne la parsez jamais.
doc_urlOuiLien stable vers la page de documentation de ce code.
request_idOuiIdentifiant de corrélation, également renvoyé dans l'en-tête de réponse X-Request-Id. Citez-le dans vos demandes au support.
paramNonLe champ en cause, lorsqu'un seul champ est fautif.
detailsNonÉchecs de validation par champ sous forme d'objets {param, message}, où param est un chemin pointé comme to[0].email. Présent uniquement dans les réponses validation_error.
vendor_codeNonCode exact provenant d'un système en aval (un code de réponse SMTP, un code de refus de paiement) lorsqu'il mérite une action.

Mappage de statut HTTP

Chaque type correspond à exactement un statut HTTP, de sorte que le statut et la réponse d'erreur ne se contredisent jamais.
StatuttypeSignification
400bad_request_errorLa requête était mal formée : un corps non analysable ou un en-tête invalide (par exemple, un Idempotency-Key incorrect).
401auth_errorLa requête contenait des identifiants manquants, invalides ou révoqués. Consultez Authentification.
402billing_errorLa requête nécessite un moyen de paiement, un solde ou un plan que l'organisation ne possède pas. Consultez Facturation et utilisation.
403permission_errorLes identifiants sont valides, mais n'ont pas l'autorisation d'effectuer cette requête. Consultez Authentification.
404not_found_errorAucune route ne correspond à ce chemin, ou la ressource n'existe pas dans cet espace de travail. Consultez Régions.
409conflict_errorLa requête entre en conflit avec l'état actuel de la ressource, y compris les conflits d'idempotence (E01004, E01005). Consultez Idempotence.
410gone_errorLa ressource existait mais a été supprimée définitivement.
412precondition_errorUne précondition de cette requête n'a pas été satisfaite.
413payload_too_large_errorLe corps de la requête dépasse la taille maximale autorisée.
421misdirected_errorLa requête a atteint une région qui ne peut pas la traiter. Consultez Régions.
422delivery_errorLe message a été accepté en tant que requête mais ne peut pas être distribué tel qu'adressé.
422validation_errorLe corps de la requête a été analysé, mais une ou plusieurs valeurs sont invalides.
425too_early_errorLa requête est arrivée plus tôt que le moment où elle peut être traitée.
429rate_limit_errorUn groupe de limitation du débit est épuisé pour cet espace de travail. Consultez Limitation du débit.
500internal_errorUn problème est survenu de notre côté lors du traitement de la requête. Consultez Idempotence.
501not_implemented_errorLe endpoint est déclaré dans le API mais pas encore implémenté.
503service_unavailable_errorUne dépendance de cette requête est temporairement indisponible.

Gestion des erreurs dans les SDK

Chaque SDK transpose la réponse d'erreur dans le modèle d'erreur natif de son langage et expose chaque champ de la réponse d'erreur (type, code, message, doc_url, request_id, …) sur la valeur d'erreur.
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;
}

Catalogue d'erreurs

Tous les codes d'erreur renvoyés par l'API publique Bird API, répartis sur une page par plage de codes. Chaque page de plage liste ses codes, et chaque code possède sa propre page avec la cause et la marche à suivre. Le doc_url de toute réponse d'erreur pointe directement vers la page de ce code.
PlageDomaineCodes
E01xxxInfrastructure27 codes
E02xxxAuth et identité8 codes, 2 retirés
E03xxxFacturation et plans11 codes
E04xxxEnvoi et distribution d'e-mails41 codes, 2 retirés
E05xxxDomaines et DNS19 codes
E06xxxWebhooks6 codes
E07xxxWallet3 codes
E10xxxQuotas4 codes, 2 retirés
E11xxxPools d'IP et IP dédiées4 codes, 1 retiré
E12xxxEnvoi et distribution SMS43 codes, 5 retirés
E13xxxVerify7 codes, 1 retiré
E14xxxNuméros5 codes
E15xxxEnvoi et distribution WhatsApp32 codes
E16xxxTrust1 code
E17xxxBoîtes aux lettres d'agents14 codes, 2 retirés
E19xxxConformité d'enregistrement4 codes
E21xxxVoix et trunking SIP1 code, 3 retirés
E22xxxRecherche de numéro4 codes
E23xxxRealtime1 code
E25xxxSendability5 codes, 1 retiré
E28xxxApple Messages for Business2 codes, 2 retirés

Ressources associées