Przyjęta wysyłka może później zakończyć się niepowodzeniem podczas dostarczania. Zachowanie nagłówków odpowiedzi pozwala wsparciu zbadać oryginalne wywołanie wraz z późniejszymi zdarzeniami dotyczącymi wiadomości.
Gdzie znajdę request ID?
Odczytaj nagłówek odpowiedzi X-Request-Id zarówno przy udanych, jak i nieudanych wywołaniach. Bird zawiera również request_id wewnątrz obiektu error najwyższego poziomu w przypadku błędów.
Zapisz nagłówek, gdy klient otrzyma odpowiedź. Umieszczaj go w logach również przy udanych wysyłkach, ponieważ nieoczekiwany wynik dostarczenia może nadejść później.
Co wysłać do wsparcia?
Wyślij request ID dotkniętej próby, jej czas, operację i nieoczekiwany wynik. Dołącz status HTTP oraz code i name błędu.
Ponowienie ma własny request ID. Jeśli pierwsza próba się nie powiodła, a druga się udała, podaj ID pierwszej próby, pytając o błąd.
Przy pytaniach o dostarczenie dołącz też message ID. Jedno żądanie wsadowe e-mail może kolejkować do 100 wiadomości pod jednym request ID.
Co powinien logować mój klient?
Loguj nagłówek odpowiedzi, status HTTP, czas żądania i operację dla każdej próby. W przypadku błędów zapisuj też code, name i request_id z odpowiedzi z błędem.
Te pola odpowiadają na różne pytania. Kod identyfikuje udokumentowany błąd. Nazwa czyni logi czytelnymi. Request ID pozwala wsparciu prześledzić próbę.
Przechowuj zwrócony message ID obok rekordu wysyłki w Twojej aplikacji. Nie loguj poświadczeń ani treści wiadomości tylko po to, żeby zachować te identyfikatory.
Jak połączyć zdarzenia z moimi własnymi rekordami?
Dołącz identyfikator swojej aplikacji, korzystając z pól obsługiwanych przez endpoint wysyłki. Przy wysyłkach e-mail metadata i tags są przekazywane w zdarzeniach webhookowych.
Na przykład identyfikator zamówienia może połączyć zdarzenie dostarczenia z zamówieniem, które wywołało wysyłkę e-maila. Request ID przechowuj oddzielnie na potrzeby badania wywołania API.
Którego identyfikatora użyć?
Używaj request ID dla pojedynczej próby API, a message ID dla historii dostarczenia.
| Identyfikator | Użyj do |
|---|---|
X-Request-Id | Zapytaj wsparcie o jedną próbę API. |
| Message ID | Śledź jedną wiadomość przez jej zdarzenia dostarczenia. |
Idempotency-Key | Ponów ten sam zapis bez celowego tworzenia kolejnej operacji. |
webhook-id | Deduplikuj powtórzone dostarczenia tego samego zdarzenia. |
Twój identyfikator w metadata lub tags | Łącz obsługiwane zdarzenia z rekordami Twojej aplikacji. |
Utrzymuj klucz idempotentności stały przy ponowieniach jednego zapisu. Request ID zmienia się z każdą próbą. Zdarzenie webhookowe zachowuje swój identyfikator przy ponowieniach dostarczenia.
Przewodnik po błędach pokazuje, gdzie request ID pojawia się w odpowiedziach z błędem.
W skrócie
Zapisuj nagłówek odpowiedzi.
X-Request-Ididentyfikuje próbę niezależnie od tego, czy się powiodła, czy nie. Błędy zawierają teżrequest_idw odpowiedzi z błędem.Traktuj każde ponowienie osobno.
Ponowienie otrzymuje nowy request ID, nawet jeśli używa tego samego klucza idempotentności.
Dołączaj message ID przy pytaniach o dostarczenie.
Jedno wywołanie API może kolejkować kilka wiadomości, więc sam request ID może nie wskazywać dotkniętego odbiorcy.
Używaj identyfikatorów aplikacji do łączenia rekordów.
Przy wysyłkach e-mail metadane i tagi przenoszą Twoje identyfikatory do zdarzeń webhookowych.