Jak zaprojektować obsługę błędów API

Oddziel błędy według źródła

Błąd walidacji, brak autoryzacji, limit liczby żądań, przekroczenie limitu czasu i odpowiedź 500 to różne sytuacje. Jeden ogólny błąd ukrywa akcję dostępną dla użytkownika lub systemu.

Określ, kto może rozwiązać problem: użytkownik, Twój kod, zewnętrzny dostawca lub administrator. To określa stan, komunikat i zasady ponawiania.

Walidacja i umowa API

Sprawdź wymagane pola, typy, długości i dozwolone wartości przed żądaniem zewnętrznym. Użytkownicy otrzymują precyzyjną informację zwrotną, a integracja nie marnuje limitów szybkości na nieprawidłowe dane.

Potwierdź również odpowiedź. Status 200 nie gwarantuje, że odpowiedź ma oczekiwaną strukturę ani że operacja biznesowa została zakończona.

• Nie ufaj danym tylko dlatego, że istnieje typ TypeScript.
• Udokumentuj wersję API i dopuszczalne wartości.
• Obsługuj brakujące pole bez zawieszania całego procesu.
• Nigdy nie udostępniaj użytkownikowi nieprzetworzonego śladu stosu.

Limity czasu, ponowne próby i limity szybkości

Każde żądanie zewnętrzne wymaga limitu czasu. Bez niego dostawca, który zawiesił się w działaniu, może bez końca blokować proces systemowy albo użytkownika.

Ponowienia powinny mieć rosnące odstępy, ścisły limit prób i losowe rozproszenie czasu. Przestrzegaj opcji Retry-After w przypadku odpowiedzi 429 i zabezpiecz płatności i operacje tworzące rekordy kluczem idempotencji.

Logi bez zdradzania tajemnic

Dzienniki mogą zawierać identyfikator żądania, kategorię punktu końcowego, stan, czas trwania i bezpieczny kontekst. Tokeny dostępu, hasła, dane kart i pełne dane osobowe nie należą do nich.

Identyfikator korelacji przechodzący przez formularz, serwer i dostawcę pomaga prześledzić jedno wywołanie bez wyszukiwania według danych osobowych.

• Maskuj tokeny i pliki cookie.
• Przechowuj dzienniki tylko tak długo, jak to konieczne.
• Oddziel komunikaty użytkownika od diagnostyki wewnętrznej.
• Wysyłaj alerty o powtarzających się awariach krytycznych.

Co powinien zobaczyć użytkownik

Komunikat powinien jasno wskazywać, czy dane zostały zapisane i co użytkownik ma zrobić dalej. Jeśli powtórzenie jest niebezpieczne, nie proś o kolejne kliknięcie przed sprawdzeniem statusu.

W przypadku długich operacji ujawniaj postęp i dostarczaj wynik asynchronicznie. Niezawodność nie polega na braku awarii; jest to przewidywalne zachowanie w przypadku wystąpienia awarii.