Erreurs

Chaque requête Bird API en échec renvoie la même réponse d'erreur JSON, imbriquée sous une clé de premier niveau error. Voici une vraie réponse à une requête d'envoi avec un corps vide :

Exemple de code

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

Le statut HTTP découle du type. Les erreurs client utilisent 400 pour les requêtes mal formées, 401 ou 403 pour les échecs d'accès, 402 pour la facturation et 404 pour les ressources introuvables. Elles utilisent 409 pour les conflits, 412 pour les préconditions non remplies, 422 pour les échecs de validation et de règles métier, et 429 pour la limitation du débit. Les erreurs côté Bird utilisent 5xx. Le statut identifie la catégorie ; la réponse d'erreur explique ce qui s'est passé.

Champs de la réponse d'erreur

Champ	Rôle
type	Catégorie générale pour un branchement grossier : validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error, et quelques autres. Un enum fermé qui évolue rarement.
code	Identifiant opaque et stable (E01001). La référence canonique : unique, jamais renommé, jamais réutilisé. Quand une erreur est retirée, son code est réservé définitivement.
name	Slug lisible par un humain (ValidationError) pour la lisibilité des logs. Toujours associé à code, jamais un substitut.
message	Description lisible par un humain. Non stable : la formulation peut changer sans préavis. Affichez-la, journalisez-la, ne la parsez jamais.
param	Pour les erreurs liées à une saisie, le champ en cause. Omis quand non applicable.
doc_url	Lien stable vers la page de documentation de ce code.
request_id	Toujours présent, et également renvoyé dans l'en-tête de réponse X-Request-Id. Citez-le dans vos demandes de support ; il permet à Bird de retrouver la requête exacte.
details	Problèmes de validation par champ. Présent uniquement dans les réponses validation_error.
remediation	Prochaine étape lisible par un humain pour résoudre l'erreur. Présent quand une résolution est connue.
next	Opérations qui résolvent l'erreur, dans l'ordre à suivre. Présent pour les erreurs avec une résolution bien définie, comme les préconditions non remplies.
vendor_code	Code exact provenant d'un système en aval (un code de réponse SMTP, un code de refus de paiement). Présent uniquement quand Bird expose un code de système externe sur lequel vous pourriez vouloir agir.

Branchez sur type pour un traitement grossier et sur code pour un traitement spécifique, jamais sur message. Un client typique aiguille sur type (réessayer sur rate_limit_error, afficher validation_error à l'utilisateur, alerter quelqu'un sur internal_error) et ne compare des valeurs code individuelles que pour les quelques erreurs qu'il gère spécialement.

Les codes tels que E04012 sont volontairement opaques. Chaque code renvoie vers une page de documentation via doc_url, qui explique la cause et la marche à suivre. Le catalogue complet se trouve dans la référence des erreurs.

Échecs de validation : un seul code, plusieurs détails

La validation par champ n'a pas de code distinct par combinaison champ-erreur. Chaque échec de validation est E01001 ValidationError avec un tableau details listant chaque problème par champ sous forme de {param, message}, comme l'échec d'envoi capturé liste ses propriétés manquantes. Les chaînes message dans details peuvent changer et ne doivent être qu'affichées. Utilisez param pour associer les problèmes aux champs du formulaire.

Conseils de résolution : remédiation et étape suivante

Les erreurs avec un correctif connu le portent dans la réponse d'erreur. Voici une vraie réponse à un appel webhooks effectué avec une clé API ne disposant pas du scope requis :

Exemple de code

{
  "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 est une phrase destinée à un humain ou à un log d'agent ; next, quand il est présent, liste les opérations API qui résolvent l'erreur dans l'ordre à suivre (vérifier un domaine, puis réessayer l'envoi). Les agents et les CLI peuvent exécuter next directement ; les clients interactifs peuvent afficher remediation tel quel.

Bien gérer les erreurs

Réessayez 429 et 5xx, rien d'autre par défaut. Respectez Retry-After pour la limitation du débit (voir Limitation du débit), utilisez un backoff exponentiel sur 5xx et envoyez un Idempotency-Key pour que les réessais de requêtes modifiantes soient sûrs.
Journalisez code, name et request_id ensemble. Le code est ce que vous rechercherez dans la documentation et vos propres logs ; l'identifiant de requête est ce dont le support a besoin.
Tolérez les nouveaux codes et types. De nouveaux codes d'erreur apparaissent régulièrement à mesure que les produits évoluent, et l'enum type gagne occasionnellement une valeur. Écrivez votre gestionnaire avec une branche par défaut raisonnable plutôt qu'un match exhaustif.

Étapes suivantes

Référence des erreurs : le catalogue complet des erreurs, une page par code
Idempotence : réessais sûrs pour les requêtes modifiantes
Limitation du débit : en-têtes de limite et conseils de backoff

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 integration Guide d'implémentationSend your first email

Obtenir un guide d'implémentation