Een geaccepteerde verzending kan later bij bezorging mislukken. Door de response-headers te bewaren kan support de oorspronkelijke aanroep onderzoeken naast de daaropvolgende events van het bericht.
Waar vind ik het request ID?
Lees de X-Request-Id response-header bij geslaagde en mislukte aanroepen. Bird bevat ook request_id in het top-level error-object bij fouten.
Sla de header op wanneer je client het antwoord ontvangt. Neem het op in logs voor geslaagde verzendingen, omdat een onverwacht bezorgresultaat later kan binnenkomen.
Wat stuur je naar support?
Stuur het request ID van de getroffen poging, het tijdstip, de operatie en het onverwachte resultaat. Vermeld de HTTP-status en eventuele fout-code en name.
Een retry heeft een eigen request ID. Als de eerste poging mislukte en de tweede slaagde, vermeld dan het ID van de eerste poging wanneer je naar de fout vraagt.
Vermeld bij bezorgvragen ook het message ID. Eén e-mail-batchverzoek kan tot 100 berichten onder één request ID in de wachtrij plaatsen.
Wat moet mijn client loggen?
Log de response-header, HTTP-status, verzoektijd en operatie voor elke poging. Leg bij fouten ook code, name en request_id uit het foutantwoord vast.
Deze velden beantwoorden afzonderlijke vragen. De code identificeert de gedocumenteerde fout. De naam maakt logs leesbaar. Het request ID laat support de poging traceren.
Bewaar het geretourneerde message ID naast het verzendrecord van je applicatie. Vermijd het loggen van inloggegevens of berichtteksten alleen om deze identifiers te behouden.
Hoe koppel ik events aan mijn eigen records?
Voeg de identifier van je applicatie toe via de velden die het verzend-endpoint ondersteunt. Bij e-mailverzendingen worden metadata en tags doorgegeven in webhook-events.
Een orderidentifier kan bijvoorbeeld een bezorgevent koppelen aan de order die de e-mail heeft geactiveerd. Bewaar het request ID apart om de API-aanroep te onderzoeken.
Welke identifier moet ik gebruiken?
Gebruik het request ID voor één API-poging en het message ID voor bezorggeschiedenis.
| Identifier | Gebruik het om |
|---|---|
X-Request-Id | Support te vragen over één API-poging. |
| Message ID | Eén bericht te volgen door zijn bezorgevents. |
Idempotency-Key | Dezelfde schrijfactie opnieuw te proberen zonder bewust een extra operatie te maken. |
webhook-id | Herhaalde bezorgingen van hetzelfde event te dedupliceren. |
Je identifier in metadata of tags | Ondersteunde events te koppelen aan de records van je applicatie. |
Houd een idempotency key stabiel bij retries van één schrijfactie. Het request ID verandert bij elke poging. Een webhook-event behoudt zijn identifier bij herhaalde bezorgpogingen.
De foutengids laat zien waar het request ID verschijnt in foutantwoorden.
Kort gezegd
Log de response-header.
X-Request-Ididentificeert de poging, ongeacht of deze slaagde of mislukte. Fouten bevatten ookrequest_idin hun foutantwoord.Houd elke retry apart.
Een retry krijgt een nieuw request ID, ook wanneer dezelfde idempotency key wordt gebruikt.
Vermeld het message ID bij bezorgvragen.
Eén API-aanroep kan meerdere berichten in de wachtrij plaatsen, dus het request ID alleen identificeert de getroffen ontvanger mogelijk niet.
Gebruik applicatie-identifiers om records te koppelen.
Bij e-mailverzendingen dragen metadata en tags je identifiers door naar webhook-events.