Un invio accettato può fallire successivamente durante la consegna. Conservare gli header della risposta permette al supporto di analizzare la chiamata originale insieme agli eventi successivi del messaggio.
Dove trovo il request ID?
Leggi l'header di risposta X-Request-Id nelle chiamate riuscite e fallite. Bird include anche request_id all'interno dell'oggetto error di primo livello nei casi di errore.
Salva l'header quando il tuo client riceve la risposta. Includilo nei log anche per gli invii riusciti, perché un risultato di consegna imprevisto può arrivare in seguito.
Cosa devo inviare al supporto?
Invia il request ID del tentativo interessato, l'orario, l'operazione e il risultato imprevisto. Includi lo stato HTTP e, se presenti, code e name dell'errore.
Un nuovo tentativo ha un proprio request ID. Se il primo tentativo è fallito e il secondo è riuscito, includi l'ID del primo tentativo quando chiedi informazioni sull'errore.
Per le domande sulla consegna, includi anche il message ID. Una richiesta email batch può accodare fino a 100 messaggi sotto un unico request ID.
Cosa deve registrare il mio client?
Registra l'header della risposta, lo stato HTTP, l'orario della richiesta e l'operazione per ogni tentativo. Per gli errori, annota anche code, name e request_id dalla risposta di errore.
Questi campi rispondono a domande diverse. Il codice identifica l'errore documentato. Il nome rende i log leggibili. Il request ID permette al supporto di tracciare il tentativo.
Conserva il message ID restituito insieme al record di invio della tua applicazione. Evita di registrare credenziali o corpi dei messaggi solo per conservare questi identificatori.
Come collego gli eventi ai miei record?
Associa l'identificatore della tua applicazione usando i campi supportati dall'endpoint di invio. Per gli invii email, metadata e tags vengono riportati negli eventi webhook.
Ad esempio, un identificatore d'ordine può collegare un evento di consegna all'ordine che ha generato l'email. Conserva il request ID separatamente per analizzare la chiamata API.
Quale identificatore devo usare?
Usa il request ID per un singolo tentativo API e il message ID per la cronologia di consegna.
| Identificatore | Usalo per |
|---|---|
X-Request-Id | Chiedere al supporto informazioni su un tentativo API. |
| Message ID | Seguire un messaggio attraverso i suoi eventi di consegna. |
Idempotency-Key | Riprovare la stessa scrittura senza creare intenzionalmente un'altra operazione. |
webhook-id | Deduplicare consegne ripetute dello stesso evento. |
Il tuo identificatore in metadata o tags | Collegare gli eventi supportati ai record della tua applicazione. |
Mantieni una chiave di idempotenza stabile tra i tentativi di una stessa scrittura. Il request ID cambia a ogni tentativo. Un evento webhook mantiene il proprio identificatore tra i tentativi di consegna.
La guida agli errori mostra dove compare il request ID nelle risposte di errore.
In breve
Registra l'header della risposta.
X-Request-Ididentifica il tentativo, sia riuscito che fallito. Gli errori includono ancherequest_idnella loro risposta di errore.Tieni separato ogni nuovo tentativo.
Un nuovo tentativo riceve un request ID diverso, anche quando usa la stessa chiave di idempotenza.
Includi il message ID per le domande sulla consegna.
Una singola chiamata API può accodare più messaggi, quindi il suo request ID da solo potrebbe non identificare il destinatario interessato.
Usa gli identificatori applicativi per collegare i record.
Negli invii email, metadata e tag portano i tuoi identificatori negli eventi webhook.