Ein akzeptierter Versand kann später bei der Zustellung fehlschlagen. Wenn Sie die Antwort-Header aufbewahren, kann der Support den ursprünglichen Aufruf zusammen mit den nachfolgenden Events der Nachricht untersuchen.
Wo finde ich die Request-ID?
Lesen Sie den X-Request-Id-Antwort-Header bei erfolgreichen und fehlgeschlagenen Aufrufen. Bird enthält bei Fehlern außerdem request_id im error-Objekt auf oberster Ebene.
Speichern Sie den Header, sobald Ihr Client die Antwort empfängt. Nehmen Sie ihn auch bei erfolgreichen Versendungen in die Logs auf, da ein unerwartetes Zustellungsergebnis später eintreffen kann.
Was sollte ich dem Support senden?
Senden Sie die Request-ID des betroffenen Versuchs, den Zeitpunkt, die Operation und das unerwartete Ergebnis. Geben Sie den HTTP-Status sowie etwaige Fehler-code und name an.
Ein Wiederholungsversuch hat eine eigene Request-ID. Falls der erste Versuch fehlschlug und der zweite erfolgreich war, geben Sie die ID des ersten Versuchs an, wenn Sie nach dem Fehler fragen.
Geben Sie bei Zustellungsfragen auch die Nachrichten-ID an. Ein einzelner E-Mail-Batch-Request kann bis zu 100 Nachrichten unter einer Request-ID in die Warteschlange stellen.
Was sollte mein Client protokollieren?
Protokollieren Sie den Antwort-Header, den HTTP-Status, den Zeitpunkt der Anfrage und die Operation für jeden Versuch. Zeichnen Sie bei Fehlern außerdem code, name und request_id aus der Fehlerantwort auf.
Diese Felder beantworten unterschiedliche Fragen. Der Code identifiziert den dokumentierten Fehler. Der Name macht Logs lesbar. Die Request-ID ermöglicht dem Support die Nachverfolgung des Versuchs.
Bewahren Sie die zurückgegebene Nachrichten-ID zusammen mit dem Versanddatensatz Ihrer Anwendung auf. Vermeiden Sie es, Zugangsdaten oder Nachrichteninhalte nur deshalb zu protokollieren, um diese Identifikatoren zu behalten.
Wie verknüpfe ich Events mit meinen eigenen Datensätzen?
Hängen Sie den Identifikator Ihrer Anwendung über die Felder an, die der Sende-Endpunkt unterstützt. Bei E-Mail-Versendungen werden metadata und tags in Webhook-Events übernommen.
Beispielsweise kann ein Bestell-Identifikator ein Zustellungsevent mit der Bestellung verknüpfen, die die E-Mail ausgelöst hat. Bewahren Sie die Request-ID separat auf, um den API-Aufruf zu untersuchen.
Welchen Identifikator sollte ich verwenden?
Verwenden Sie die Request-ID für einen einzelnen API-Versuch und die Nachrichten-ID für die Zustellungshistorie.
| Identifikator | Verwenden Sie ihn, um |
|---|---|
X-Request-Id | Den Support zu einem einzelnen API-Versuch zu befragen. |
| Nachrichten-ID | Eine Nachricht durch ihre Zustellungsevents zu verfolgen. |
Idempotency-Key | Denselben Schreibvorgang zu wiederholen, ohne absichtlich eine weitere Operation zu erzeugen. |
webhook-id | Wiederholte Zustellungen desselben Events zu deduplizieren. |
Ihr Identifikator in metadata oder tags | Unterstützte Events mit den Datensätzen Ihrer Anwendung zu verknüpfen. |
Halten Sie einen Idempotenzschlüssel über Wiederholungsversuche eines Schreibvorgangs hinweg stabil. Die Request-ID ändert sich mit jedem Versuch. Ein Webhook-Event behält seinen Identifikator über Zustellungswiederholungen hinweg bei.
Der Fehler-Leitfaden zeigt, wo die Request-ID in Fehlerantworten erscheint.
Kurz gesagt
Protokollieren Sie den Antwort-Header.
X-Request-Ididentifiziert den Versuch, unabhängig davon, ob er erfolgreich war oder fehlschlug. Fehler enthalten außerdemrequest_idin ihrer Fehlerantwort.Behandeln Sie jeden Wiederholungsversuch separat.
Ein Wiederholungsversuch erhält eine neue Request-ID, selbst wenn er denselben Idempotenzschlüssel verwendet.
Geben Sie die Nachrichten-ID bei Zustellungsfragen an.
Ein einzelner API-Aufruf kann mehrere Nachrichten in die Warteschlange stellen, sodass seine Request-ID allein den betroffenen Empfänger möglicherweise nicht identifiziert.
Verwenden Sie Anwendungs-Identifikatoren, um Datensätze zu verknüpfen.
Bei E-Mail-Versendungen übertragen Metadaten und Tags Ihre Identifikatoren in Webhook-Events.