Un envoi accepté peut échouer plus tard lors de la livraison. Conserver ses en-têtes de réponse permet au support d'examiner l'appel d'origine en parallèle des événements ultérieurs du message.
Où trouver le request ID ?
Lisez l'en-tête de réponse X-Request-Id sur les appels réussis comme échoués. Bird inclut aussi request_id dans l'objet error de premier niveau en cas d'échec.
Enregistrez l'en-tête dès que votre client reçoit la réponse. Incluez-le dans les logs même pour les envois réussis, car un résultat de livraison inattendu peut survenir plus tard.
Que faut-il envoyer au support ?
Envoyez le request ID de la tentative concernée, son horodatage, l'opération et le résultat inattendu. Incluez le statut HTTP ainsi que les éventuels code et name d'erreur.
Un nouvel essai possède son propre request ID. Si la première tentative a échoué et la seconde a réussi, incluez l'ID de la première tentative lorsque vous signalez l'échec.
Pour les questions de livraison, incluez aussi le message ID. Une seule requête d'envoi groupé d'e-mails peut mettre en file d'attente jusqu'à 100 messages sous un même request ID.
Que doit enregistrer mon client ?
Enregistrez l'en-tête de réponse, le statut HTTP, l'horodatage de la requête et l'opération pour chaque tentative. En cas d'erreur, enregistrez aussi code, name et request_id depuis la réponse d'erreur.
Ces champs répondent à des questions distinctes. Le code identifie l'échec documenté. Le nom rend les logs lisibles. Le request ID permet au support de retracer la tentative.
Conservez le message ID retourné aux côtés de l'enregistrement d'envoi de votre application. Évitez de journaliser des identifiants ou le corps des messages uniquement pour conserver ces identifiants.
Comment relier les événements à mes propres enregistrements ?
Associez l'identifiant de votre application en utilisant les champs pris en charge par le endpoint d'envoi. Pour les envois d'e-mails, metadata et tags sont repris dans les événements webhook.
Par exemple, un identifiant de commande peut relier un événement de livraison à la commande ayant déclenché l'e-mail. Conservez le request ID séparément pour examiner l'appel API.
Quel identifiant utiliser ?
Utilisez le request ID pour une tentative API et le message ID pour l'historique de livraison.
| Identifiant | Utilisation |
|---|---|
X-Request-Id | Interroger le support sur une tentative API. |
| Message ID | Suivre un message à travers ses événements de livraison. |
Idempotency-Key | Réessayer la même écriture sans créer volontairement une autre opération. |
webhook-id | Dédupliquer les livraisons répétées d'un même événement. |
Votre identifiant dans metadata ou tags | Relier les événements pris en charge aux enregistrements de votre application. |
Gardez une clé d'idempotence stable d'un essai à l'autre pour une même écriture. Le request ID change à chaque tentative. Un événement webhook conserve son identifiant d'un essai de livraison à l'autre.
Le guide des erreurs indique où le request ID apparaît dans les réponses d'erreur.
En bref
Enregistrez l'en-tête de réponse.
X-Request-Ididentifie la tentative, qu'elle ait réussi ou échoué. Les erreurs incluent aussirequest_iddans leur réponse d'erreur.Séparez chaque nouvel essai.
Un nouvel essai reçoit un nouveau request ID, même s'il utilise la même clé d'idempotence.
Incluez le message ID pour les questions de livraison.
Un seul appel API peut mettre en file d'attente plusieurs messages ; son request ID seul ne suffit donc pas toujours à identifier le destinataire concerné.
Utilisez les identifiants applicatifs pour relier les enregistrements.
Pour les envois d'e-mails, les métadonnées et les tags transmettent vos identifiants dans les événements webhook.