Nieudane żądanie może wymagać opóźnienia, poprawionego pola lub innych danych uwierzytelniających. Odpowiedź z błędem Bird zawiera pola, które handler może wykorzystać do wyboru odpowiedniego działania.
Których pól błędu używać?
Używaj type do ogólnej obsługi, a code do konkretnego działania naprawczego. Bird umieszcza te pola wewnątrz obiektu najwyższego poziomu error.
Typ grupuje błędy takie jak walidacja, uwierzytelnianie i ograniczanie liczby żądań. Kod identyfikuje konkretny błąd, na przykład E01001 dla walidacji pól.
Bird nigdy nie zmienia nazwy ani nie używa ponownie kodu. Wycofane kody pozostają zarezerwowane, więc istniejące dopasowanie kodu zachowuje swoje znaczenie.
Wyświetlaj lub loguj message, ale nie dopasowuj jego tekstu. Treść komunikatu może się zmienić bez zmiany błędu, który handler musi obsłużyć.
name zwiększa czytelność logów. doc_url prowadzi do dokumentacji kodu. Loguj code, name i request_id razem, gdy operacja się nie powiedzie.
Które błędy ponawiać?
Ponawiaj tymczasowe błędy z ograniczoną liczbą prób. Napraw problemy z danymi wejściowymi i uwierzytelnianiem przed kolejną próbą. Sprawdź konkretny kod, gdy jeden status może wymagać różnych działań.
| Odpowiedź | Domyślne działanie |
|---|---|
429, E01003 | Poczekaj na Retry-After, a potem spróbuj ponownie. |
500, 502, 503 lub 504 | Ponawiaj z rosnącymi odstępami i limitem prób. |
501 | Zatrzymaj się i sprawdź, jakie operacje obsługuje serwer. |
401 lub 403 | Popraw dane uwierzytelniające lub ich uprawnienia przed ponowieniem. |
| Walidacja pól lub nieprawidłowe dane wejściowe | Popraw pola wskazane w odpowiedzi. |
409, E01004 | Poczekaj na zakończenie trwającej operacji przed ponowieniem. |
409, E01005 | Popraw ponowne użycie klucza idempotentności z innymi danymi wejściowymi. |
Używaj tego samego klucza idempotentności przy ponawianiu tego samego zapisu. Timeout lub błąd serwera nie dowodzi, że oryginalna operacja nic nie zrobiła.
Zatrzymaj się, gdy budżet ponowień się wyczerpie, i zapisz ostatni błąd. Nieskończone powtarzanie niezmienionego żądania może ukryć problem wymagający interwencji.
Jak obsługiwać błędy walidacji pól?
Odczytaj tablicę details z E01001 ValidationError i powiąż każdy wpis z jego param. Wyświetl message tego wpisu obok odpowiedniego pola.
Nie parsuj tych komunikatów, aby zidentyfikować pole lub błąd. Ich treść może się zmienić, tak jak komunikat najwyższego poziomu.
Nieprawidłowo sformułowane żądanie może zamiast tego zwrócić E01002 InvalidRequest. Zastosuj udokumentowaną procedurę naprawczą zamiast zakładać, że każdy błąd danych wejściowych zawiera szczegóły na poziomie pól.
Czy odpowiedź podpowiada, jak naprawić problem?
Niektóre błędy zawierają remediation, czytelny dla człowieka następny krok, lub next, uporządkowaną listę operacji do wykonania.
Wyświetl wskazówkę naprawczą, gdy pomoże użytkownikowi rozwiązać problem. Na przykład błąd autoryzacji może wymagać danych uwierzytelniających z dodatkowym zakresem uprawnień.
Zautomatyzowany handler może użyć next, aby wybrać operację naprawczą. Nadal potrzebuje danych wejściowych i uprawnień tej operacji, zanim ją wykona.
vendor_code identyfikuje błąd po stronie zewnętrznego dostawcy, na przykład odpowiedź SMTP lub odrzucenie płatności. Sprawdź kod tego dostawcy, gdy naprawa od niego zależy.
Co zrobić z nieznanym kodem?
Zachowaj domyślną gałąź, która zapisuje błąd bez powodowania awarii i nieskończonego ponawiania. Nowe kody i typy mogą się pojawiać wraz z rozwojem API.
Zastosuj znaną politykę ponawiania opartą na statusie, jeśli to możliwe. W przeciwnym razie zatrzymaj się i zaloguj kod wraz z jego identyfikatorem żądania do zbadania.
Przewodnik po błędach dokumentuje strukturę odpowiedzi z błędem. Referencja błędów wymienia poszczególne kody i wskazówki dotyczące naprawy.
W skrócie
Dopasowuj kody, nie komunikaty.
Bird nigdy nie zmienia nazw ani nie używa ponownie kodów błędów, ale komunikaty czytelne dla człowieka mogą się zmieniać.
Ponawiaj tymczasowe błędy z limitem prób.
Czekaj przy limitach liczby żądań i wydłużaj odstępy przy tymczasowych błędach serwera. Używaj tego samego klucza idempotentności przy ponawianym zapisie.
Czytaj szczegóły walidacji.
E01001zawiera problemy z polami wdetails. Użyj każdegoparam, aby powiązać jego komunikat z danym polem wejściowym.Zachowaj domyślną obsługę nieznanych błędów.
Loguj nieznane kody i ich identyfikatory żądań, aby nowe błędy nie powodowały awarii handlera.