Messages d'erreur courants
Quand une requête échoue, Bird renvoie une réponse d'erreur structurée contenant un code lisible par la machine, un message, un lien vers la documentation et un identifiant de requête. Utilisez le code dans votre logique applicative. Si vous avez besoin d'aide, sélectionnez Feedback > Contact us et joignez l'identifiant de requête. Pour le catalogue complet, consultez la référence des erreurs API.
Erreurs de validation
Ces erreurs signifient que Bird a compris votre requête, mais qu'un élément n'est pas acceptable. L'erreur indique le champ ou la condition en cause.
Tous les destinataires supprimés
Ce que cela signifie : chaque destinataire de votre envoi figure sur votre liste de suppression, il ne restait donc rien à livrer et l'envoi a été refusé.
Cause probable : vous envoyez à des adresses qui ont précédemment généré un hard bounce, une plainte ou un désabonnement, souvent le signe que vous renvoyez vers une liste ancienne ou non nettoyée. Si seulement certains destinataires sont supprimés, l'envoi aboutit pour les autres et les supprimés apparaissent comme rejetés ; cette erreur ne survient que lorsqu'ils le sont tous.
Correctif : vérifiez quelles adresses sont supprimées et pourquoi, puis retirez-les de votre propre liste. Why was my email rejected? explique comment les rejets par suppression apparaissent, et le guide des suppressions couvre la gestion de la liste.
Destinataire d'onboarding non autorisé
Ce que cela signifie : vous envoyez depuis le domaine d'onboarding partagé de Bird à quelqu'un qui n'est pas un membre vérifié de votre espace de travail.
Cause probable : le domaine partagé ne livre qu'aux membres vérifiés de l'espace de travail et aux adresses de test sandbox.
Correctif : pour envoyer des e-mails à de vrais destinataires, vérifiez votre propre domaine d'envoi, ce qui supprime entièrement la restriction. Consultez Sending from the shared domain pour les garde-fous et la marche à suivre.
Champ manquant ou invalide
Ce que cela signifie : un champ obligatoire est absent, une valeur est invalide, ou la requête combine des champs incompatibles.
Cause probable : la requête ne correspond pas au schéma de l'opération ou combine des champs incompatibles. Les détails de l'erreur identifient chaque champ en défaut.
Correctif : lisez les détails de l'erreur et corrigez les champs indiqués.
Erreurs de limitation du débit
Ce que cela signifie : la requête a dépassé une limite d'opération, de compte ou d'envoi.
Cause probable : une rafale a dépassé une limite de débit API, ou un envoi a dépassé un quota tel que le plafond de destinataires du domaine d'onboarding partagé.
Correctif : suivez la remédiation indiquée dans l'erreur et la valeur Retry-After lorsqu'elle est présente. Réessayez les limites transitoires avec un backoff. Pour le plafond quotidien d'onboarding, attendez la réinitialisation du jour UTC ou vérifiez votre propre domaine d'envoi. Le label de santé e-mail throttled est diagnostique et ne provoque pas d'erreur de limitation du débit API.
Erreurs d'authentification
Ce que cela signifie : Bird n'a pas pu accepter vos identifiants.
Cause probable : l'une de ces trois situations, par ordre approximatif de fréquence :
- Clé API erronée, expirée ou révoquée : la clé est mal saisie, tronquée, expirée ou inactive. Un secret n'est affiché qu'au moment de la création ou de la rotation de la clé.
- Clé utilisée dans la mauvaise région : les clés API sont régionales, et une clé ne fonctionne que sur les serveurs de sa propre région. Si votre clé a été créée dans une région et que votre code appelle une autre région, l'authentification échoue. Le préfixe de la clé indique à quelle région elle appartient.
- Clé absente : la requête n'incluait aucun identifiant, souvent une variable d'environnement vide dans l'environnement en défaut.
Correctif : confirmez que la clé existe et est active dans votre dashboard, que votre code l'envoie, et que vous appelez l'adresse régionale correspondant à la clé. En cas de doute, créez une nouvelle clé et remplacez l'ancienne.
Domaine non vérifié
Ce que cela signifie : le domaine d'envoi n'a pas terminé la vérification, Bird ne peut donc pas envoyer depuis celui-ci.
Cause probable : les enregistrements DNS sont manquants, en cours de propagation ou incorrects, ou les enregistrements ont changé après la vérification. Consultez la checklist de vérification de domaine pour les délais attendus.
Correctif : ouvrez la page du domaine dans le dashboard pour identifier l'enregistrement manquant. Utilisez la checklist de vérification de domaine pour le corriger. Pendant la propagation DNS, utilisez le domaine d'onboarding partagé pour vos envois de test.
Lire n'importe quelle erreur rencontrée
Basez-vous sur le code d'erreur lisible par la machine, car les messages textuels peuvent changer. Journalisez l'identifiant de requête. Si vous avez besoin d'aide, sélectionnez Feedback > Contact us et joignez-le. Suivez le lien de documentation pour la remédiation propre à l'erreur.
Étapes suivantes
- Référence des erreurs API (le catalogue complet : chaque type d'erreur, code et statut)
- Why was my email rejected? : les raisons derrière les rejets par destinataire
- Why does email health show Throttled? : le label diagnostique de santé et les signaux sous-jacents
- Sending from the shared domain : les garde-fous de destinataires et de plafond quotidien du domaine d'onboarding
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideWhat happens when someone opts outComprendre le conceptWhat is one-click unsubscribe, and how do I implement List-Unsubscribe?Explorer la fonctionnalitéEmail opt-outsSuivre le parcours d'apprentissageOperate messaging reliably
Obtenir un guide d'implémentation