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
| Champ | Toujours présent | Description |
|---|---|---|
| type | Oui | Catégorie générale pour un branchement grossier : une énumération fermée (auth_error, validation_error, rate_limit_error, …). |
| code | Oui | Identifiant opaque et stable correspondant à E\d{5}. Unique, jamais renommé, jamais réutilisé ; la valeur canonique sur laquelle baser vos correspondances. |
| name | Oui | Slug lisible (ValidationError) pour faciliter la lecture des logs. Toujours associé à code, jamais un substitut. |
| message | Oui | Description lisible. Non stable ; affichez-la ou journalisez-la, ne la parsez jamais. |
| doc_url | Oui | Lien stable vers la page de documentation de ce code. |
| request_id | Oui | Identifiant de corrélation, également renvoyé dans l'en-tête de réponse X-Request-Id. Citez-le dans vos demandes au support. |
| param | Non | Le champ en cause, lorsqu'un seul champ est fautif. |
| details | Non | É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_code | Non | Code 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.
| Statut | type | Signification |
|---|---|---|
| 400 | bad_request_error | La requête était mal formée : un corps non analysable ou un en-tête invalide (par exemple, un Idempotency-Key incorrect). |
| 401 | auth_error | La requête contenait des identifiants manquants, invalides ou révoqués. Consultez Authentification. |
| 402 | billing_error | La requête nécessite un moyen de paiement, un solde ou un plan que l'organisation ne possède pas. Consultez Facturation et utilisation. |
| 403 | permission_error | Les identifiants sont valides, mais n'ont pas l'autorisation d'effectuer cette requête. Consultez Authentification. |
| 404 | not_found_error | Aucune route ne correspond à ce chemin, ou la ressource n'existe pas dans cet espace de travail. Consultez Régions. |
| 409 | conflict_error | La requête entre en conflit avec l'état actuel de la ressource, y compris les conflits d'idempotence (E01004, E01005). Consultez Idempotence. |
| 410 | gone_error | La ressource existait mais a été supprimée définitivement. |
| 412 | precondition_error | Une précondition de cette requête n'a pas été satisfaite. |
| 413 | payload_too_large_error | Le corps de la requête dépasse la taille maximale autorisée. |
| 421 | misdirected_error | La requête a atteint une région qui ne peut pas la traiter. Consultez Régions. |
| 422 | delivery_error | Le message a été accepté en tant que requête mais ne peut pas être distribué tel qu'adressé. |
| 422 | validation_error | Le corps de la requête a été analysé, mais une ou plusieurs valeurs sont invalides. |
| 425 | too_early_error | La requête est arrivée plus tôt que le moment où elle peut être traitée. |
| 429 | rate_limit_error | Un groupe de limitation du débit est épuisé pour cet espace de travail. Consultez Limitation du débit. |
| 500 | internal_error | Un problème est survenu de notre côté lors du traitement de la requête. Consultez Idempotence. |
| 501 | not_implemented_error | Le endpoint est déclaré dans le API mais pas encore implémenté. |
| 503 | service_unavailable_error | Une 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;
}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();
}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.
| Plage | Domaine | Codes |
|---|---|---|
| E01xxx | Infrastructure | 27 codes |
| E02xxx | Auth et identité | 8 codes, 2 retirés |
| E03xxx | Facturation et plans | 11 codes |
| E04xxx | Envoi et distribution d'e-mails | 41 codes, 2 retirés |
| E05xxx | Domaines et DNS | 19 codes |
| E06xxx | Webhooks | 6 codes |
| E07xxx | Wallet | 3 codes |
| E10xxx | Quotas | 4 codes, 2 retirés |
| E11xxx | Pools d'IP et IP dédiées | 4 codes, 1 retiré |
| E12xxx | Envoi et distribution SMS | 43 codes, 5 retirés |
| E13xxx | Verify | 7 codes, 1 retiré |
| E14xxx | Numéros | 5 codes |
| E15xxx | Envoi et distribution WhatsApp | 32 codes |
| E16xxx | Trust | 1 code |
| E17xxx | Boîtes aux lettres d'agents | 14 codes, 2 retirés |
| E19xxx | Conformité d'enregistrement | 4 codes |
| E21xxx | Voix et trunking SIP | 1 code, 3 retirés |
| E22xxx | Recherche de numéro | 4 codes |
| E23xxx | Realtime | 1 code |
| E25xxx | Sendability | 5 codes, 1 retiré |
| E28xxx | Apple Messages for Business | 2 codes, 2 retirés |
Ressources associées
- Concepts d'erreurs : stratégie de branchement, détails de validation et sémantique vendor_code
- Authentification : identifiants derrière 401 et 403
- En-tête Idempotency-Key : les erreurs de conflit 409 et les nouvelles tentatives sûres
- Limitation du débit : groupes, en-têtes et gestion de 429
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first email
Obtenir un guide d'implémentation