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.
Po których błędach spróbować ponownie?
Po tymczasowych błędach spróbuj ponownie 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 odczyty z rosnącymi odstępami i limitem prób; zapisy podlegają zasadom idempotentności. |
501 | Zatrzymaj się i sprawdź, jakie operacje obsługuje serwer. |
401 lub 403 | Popraw dane uwierzytelniające lub ich uprawnienia przed ponowną próbą. |
| Walidacja pól lub nieprawidłowe dane wejściowe | Popraw pola wskazane w odpowiedzi. |
409, E01004 | Poczekaj na zakończenie trwającej operacji przed ponowną próbą. |
409, E01005 | Popraw ponowne użycie klucza idempotentności z innymi danymi wejściowymi. |
Gwarancja idempotentności zapewnia jednokrotne przyjęcie pasujących ponownych prób w ciągu trzech godzin. Ponawiaj zapis z tym samym kluczem i identycznym żądaniem, z ograniczoną liczbą prób i rosnącymi odstępami. Po przekroczeniu limitu czasu lub błędzie serwera nie wiadomo, czy żądanie zostało przyjęte. Zmiana klucza tworzy osobną operację. Gdy wyczerpiesz ponowne próby lub upłynie okres przechowywania, traktuj wynik jako nierozstrzygnięty do czasu jego uzgodnienia.
Zatrzymaj się, gdy budżet ponownych prób 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.
Tam, gdzie to stosowne, zastosuj znaną politykę ponownych prób opartą na statusie. W przeciwnym razie zatrzymaj się i zaloguj kod wraz z jego identyfikatorem żądania, aby zbadać problem.
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.
Przy limitach liczby żądań czekaj, a przy tymczasowych błędach serwera wydłużaj odstępy między próbami. W trzygodzinnym oknie idempotentności używaj tego samego klucza i identycznego żądania.
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.