Obsługa błędów

Format odpowiedzi

Odpowiedzi błędów API mają nagłówek Content-Type: application/json, a struktura treści odpowiada formatowi problem details z RFC 7807: pola type, title, status oraz detail. Błędy walidacji danych wejściowych dodatkowo zawierają pole errors — słownik nazw pól z listą komunikatów dla każdego z nich.

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "email": ["email must be a valid email address"]
    }
}

Kody statusów

• 400 Bad Request — nieprawidłowe dane wejściowe (błąd walidacji); ciało odpowiedzi zawiera szczegóły w polu errors.
• 401 Unauthorized — brak tokenu lub token nieprawidłowy/wygasły. Odpowiedź na brak poprawnych danych uwierzytelniających może nie zawierać ciała JSON — sprawdzaj przede wszystkim sam status.
• 403 Forbidden — token poprawny, ale konto nie ma uprawnień do żądanej operacji lub zasobu (np. rola lub zakres lokalizacji na to nie pozwala).
• 404 Not Found — żądany zasób nie istnieje lub nie należy do wskazanej organizacji.
• 429 Too Many Requests — przekroczony limit zapytań — zobacz stronę o limitach zapytań.

Zalecenia

Traktuj kod statusu HTTP jako główne źródło prawdy o typie błędu, a pola title / detail / errors jako dodatkowy, czytelny dla człowieka opis.