Un envío aceptado puede fallar después durante la entrega. Conservar los encabezados de respuesta permite a soporte investigar la llamada original junto con los eventos posteriores del mensaje.
¿Dónde encuentro el request ID?
Lee el encabezado de respuesta X-Request-Id en llamadas exitosas y fallidas. Bird también incluye request_id dentro del objeto error de nivel superior en los fallos.
Guarda el encabezado cuando tu cliente reciba la respuesta. Inclúyelo en los registros de envíos exitosos, ya que un resultado de entrega inesperado puede llegar después.
¿Qué debo enviar a soporte?
Envía el request ID del intento afectado, su hora, la operación y el resultado inesperado. Incluye el estado HTTP y cualquier code y name de error.
Un reintento tiene su propio request ID. Si el primer intento falló y el segundo tuvo éxito, incluye el ID del primer intento cuando preguntes por el fallo.
Para preguntas sobre entrega, incluye también el message ID. Una solicitud de lote de correo electrónico puede encolar hasta 100 mensajes bajo un solo request ID.
¿Qué debe registrar mi cliente?
Registra el encabezado de respuesta, el estado HTTP, la hora de la solicitud y la operación de cada intento. Para errores, registra también code, name y request_id de la respuesta de error.
Estos campos responden preguntas distintas. El código identifica el fallo documentado. El nombre hace los registros legibles. El request ID permite a soporte rastrear el intento.
Conserva el message ID devuelto junto al registro de envío de tu aplicación. Evita registrar credenciales o cuerpos de mensaje solo para retener estos identificadores.
¿Cómo conecto los eventos con mis propios registros?
Adjunta el identificador de tu aplicación usando los campos que admite el endpoint de envío. Para envíos de correo electrónico, metadata y tags se replican en los eventos de webhook.
Por ejemplo, un identificador de pedido puede conectar un evento de entrega con el pedido que generó el correo electrónico. Conserva el request ID por separado para investigar la llamada a API.
¿Qué identificador debo usar?
Usa el request ID para un intento de API y el message ID para el historial de entrega.
| Identificador | Úsalo para |
|---|---|
X-Request-Id | Preguntar a soporte sobre un intento de API. |
| Message ID | Seguir un mensaje a través de sus eventos de entrega. |
Idempotency-Key | Reintentar la misma escritura sin crear deliberadamente otra operación. |
webhook-id | Deduplicar entregas repetidas del mismo evento. |
Tu identificador en metadata o tags | Unir eventos compatibles con los registros de tu aplicación. |
Mantén una clave de idempotencia estable entre reintentos de una misma escritura. El request ID cambia con cada intento. Un evento de webhook conserva su identificador entre reintentos de entrega.
La guía de errores muestra dónde aparece el request ID en las respuestas de error.
En resumen
Registra el encabezado de respuesta.
X-Request-Ididentifica el intento, haya tenido éxito o no. Los errores también incluyenrequest_iden su respuesta de error.Mantén cada reintento separado.
Un reintento recibe un nuevo request ID, incluso cuando usa la misma clave de idempotencia.
Incluye el message ID para preguntas sobre entrega.
Una llamada a API puede encolar varios mensajes, por lo que su request ID por sí solo puede no identificar al destinatario afectado.
Usa identificadores de aplicación para unir registros.
En envíos de correo electrónico, los metadatos y las etiquetas llevan tus identificadores a los eventos de webhook.