422 Unprocessable Entity: co oznacza i jak naprawić

Co oznacza 422 Unprocessable Entity

422 wywodzi się z WebDAV (RFC 4918), a potem zostało szeroko przyjęte przez REST API jako standardowa odpowiedź dla semantycznych awarii walidacji. RFC 9110 formalnie zmieniło tekst statusu na 422 Unprocessable Content, porzucając specyficzne dla WebDAV słowo "Entity", choć obie nazwy opisują identyczny kod statusu, a "Unprocessable Entity" pozostaje dużo częstszą etykietą w domyślnych ustawieniach frameworków i dokumentacji API. Rozróżnienie, które ma znaczenie, to składnia kontra semantyka: JSON sparsował się poprawnie, każdy wymagany typ pola się zgadza, a żądanie jest poprawnie sformułowane pod każdym względem strukturalnym, ale wartość w nim narusza regułę biznesową, na przykład adres e-mail w złym formacie, data w przeszłości tam, gdzie wymagana jest przyszła, albo pole odwołujące się do rekordu, który nie istnieje.

Jak pojawia się błąd

422 niemal nigdy nie pojawia się jako błąd nawigacji w przeglądarce, bo jest to przede wszystkim odpowiedź API, nie coś wywoływane bezpośrednio przez link czy wysłanie formularza; pokazuje się w zakładce sieciowej, komunikacie błędu albo nieudanej asercji testu. Z linii poleceń treść odpowiedzi to miejsce, gdzie leży użyteczny szczegół:

curl -i -X POST https://api.example.com/v1/users   -H "Content-Type: application/json"   -d '{"email": "not-an-email", "age": -5}'

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"errors": {"email": ["is not a valid email"], "age": ["must be greater than 0"]}}

Większość dobrze zbudowanych API zwraca ustrukturyzowaną treść błędu razem z 422, nazywając dokładnie, które pole zawiodło i dlaczego, zamiast zostawiać wywołującego zgadującym po samym kodzie statusu.

Co powoduje 422 Unprocessable Entity

• Błędy walidacji w REST API. Aplikacje Rails powszechnie zwracają 422 automatycznie, gdy model ActiveRecord zawiedzie walidację przy tworzeniu albo aktualizacji. Walidacja form request Laravela domyślnie zwraca 422 dla nieudanych reguł. FastAPI, zbudowane na Pydantic, zwraca 422, gdy tylko dane żądania zawiodą kontrolę typu albo ograniczenia modelu Pydantic, dlatego jest to jeden z najczęściej widywanych kodów statusu konkretnie w projektach FastAPI.
• Pole z właściwym typem, ale nieprawidłową wartością. String tam, gdzie oczekiwano stringa, ale taki, który zawodzi kontrolę formatu, limit długości albo listę dopuszczonych wartości.
• Odwołanie do czegoś, co nie istnieje. Klucz obcy, id użytkownika albo slug w treści żądania, który jest poprawny składniowo, ale nie odpowiada żadnemu prawdziwemu rekordowi.
• Reguły biznesowe poza prostą walidacją pola. Kod rabatowy poprawny składniowo, ale wygasły, albo ilość będąca poprawną liczbą całkowitą, ale przekraczająca dostępny zapas.
• Całkowicie brakujące wymagane pole. Zależnie od frameworka, brakujące wymagane pole może zwrócić 422 zamiast 400, bo żądanie parsuje się dobrze, po prostu brakuje wartości, której wymaga warstwa walidacji.

422 kontra 400

Linia podziału to składnia kontra semantyka. 400 Bad Request oznacza, że serwer w ogóle nie mógł sparsować żądania, na przykład wadliwy JSON albo treść niepoprawna według żadnej reguły strukturalnej. 422 oznacza, że żądanie sparsowało się bez problemu i każde pole ma właściwy typ, ale wartość w nim zawodzi regułę sprawdzaną przez aplikację po parsowaniu. W praktyce wiele API zaciera to rozróżnienie i używa 400 dla obu przypadków, co jest obronne, ale mniej precyzyjne; klient integrujący się z API powinien czytać treść odpowiedzi zamiast polegać wyłącznie na kodzie statusu, żeby dokładnie wiedzieć, co zawiodło.

Jak naprawić błąd 422

Jeśli jesteś klientem wywołującym API

1. Przeczytaj treść odpowiedzi, nie tylko kod statusu. Odpowiedź 422 dobrze zbudowanego API nazywa konkretne pole i regułę, która zawiodła, co mówi Ci dokładnie, co poprawić bez dalszego zgadywania.
2. Sprawdź pole względem udokumentowanych ograniczeń API, takich jak format, długość i dopuszczone wartości, bo to reguły biznesowe, których sam schemat Ci nie pokaże.
3. Traktuj 422 jako sygnał do naprawienia danych, nie do ponowienia niezmienionego żądania. Ponowienie niezmodyfikowanego żądania, które zawiodło walidację, zawiedzie identycznie za każdym razem; dobrze zachowujący się klient powinien pokazać konkretny błąd użytkownikowi, a nie po cichu go ponawiać.

Jeśli prowadzisz API

1. Zawsze zwracaj ustrukturyzowaną treść błędu razem z 422, nazywając pole i regułę, która zawiodła, zamiast gołego kodu statusu bez wyjaśnienia.
2. Utrzymuj komunikaty błędów walidacji konkretne i praktyczne, na przykład "email must be a valid address" zamiast ogólnego "validation failed", które zmusza wywołującego do zgadywania, które z kilku pól było problemem.
3. Świadomie zdecyduj między 400 a 422 dla swojego API i udokumentuj tę decyzję, żeby integratorzy mogli zbudować niezawodną obsługę błędów zamiast traktować każde 4xx tak samo.
4. Loguj podczas developmentu payloady zwalidowane-ale-odrzucone, żeby wyłapać przypadki, gdy Twój własny kod klienta wysyła dane konsekwentnie zawodzące walidację, co często wskazuje na niedopasowanie między klientem a rzeczywistymi regułami API.

Jak klient powinien obsłużyć odpowiedź 422

Dobrze zaprojektowany klient traktuje 422 jako fundamentalnie różne od błędu 5xx albo awarii sieci: oznacza, że serwer jest zdrowy i działa poprawnie, a wywołujący wysłał coś, czego serwer nigdy nie zaakceptuje w obecnej formie. Właściwą reakcją jest sparsować treść błędu, zmapować każde zawiedzione pole z powrotem na formularz albo dane wejściowe, które je wyprodukowały, i pokazać użytkownikowi coś praktycznego, nie ponawiać z opóźnieniem tak, jak zrobiłbyś to przy timeoucie albo 503. Zautomatyzowane testy sprawdzające warstwę walidacji API powinny sprawdzać asercją konkretną treść błędu, nie tylko status 422, bo to potwierdza, że sama logika walidacji jest poprawna.

Jak zapobiec, żeby 422 przechodziły niezauważone

Reguła walidacji, która niespodziewanie się zmieniła, czy to przez wdrożenie, aktualizację biblioteki zewnętrznej, czy migrację schematu, może po cichu zacząć odrzucać żądania, które wcześniej się udawały. Kontrola HTTP, która wysyła znany dobry payload i sprawdza asercją oczekiwany kod statusu, wyłapuje taką regresję natychmiast po wdrożeniu. Dla API z więcej niż jednym endpointem albo payloadem, którego sam kod statusu nie zweryfikuje w pełni, monitorowanie API, które sprawdza też treść odpowiedzi, potwierdza samą logikę walidacji, nie tylko to, że serwer jest osiągalny.

Powiązane błędy

Zobacz 400 Bad Request dla przypadku niemożliwego sparsowania żądania, z którym kontrastuje ten poradnik, przegląd 4xx dla szerszej rodziny oraz 401 Unauthorized i 405 Method Not Allowed gdzie indziej w tej partii.

Najczęściej zadawane pytania

Czy 422 Unprocessable Entity to to samo co 422 Unprocessable Content?

Tak. RFC 9110 zmieniło frazę powodu na Unprocessable Content, ale to ten sam kod statusu o tym samym znaczeniu; większość frameworków i dokumentacji API wciąż używa starszego sformułowania Unprocessable Entity.

Dlaczego moja aplikacja FastAPI zwraca 422 dla brakującego pola?

FastAPI automatycznie waliduje dane żądania względem Twoich modeli Pydantic, a brakujące wymagane pole, albo takie z niewłaściwym typem, zawodzi tę walidację i zwraca 422 z treścią opisującą dokładnie, które pole i reguła zawiodły.

Czy powinienem ponowić żądanie, które dostało 422?

Tylko po zmianie danych, które zawiodły walidację. Ponowienie identycznego żądania wyprodukuje identyczne 422 za każdym razem, bo serwer poprawnie i konsekwentnie odrzuca te same nieprawidłowe dane wejściowe.

Jaka jest różnica między 422 a 400 w praktyce?

400 jest dla żądania, którego serwer w ogóle nie potrafi sparsować. 422 jest dla żądania, które parsuje się dobrze, ale zawiera wartość zawodzącą regułę walidacji albo biznesową. Wiele realnych API używa 400 dla obu przypadków, więc zawsze sprawdź udokumentowaną konwencję konkretnego API, które wywołujesz.

Czy 422 może oznaczać błąd po stronie serwera?

Może, jeśli sama reguła walidacji jest zła, na przykład odrzuca zupełnie poprawny format e-maila. Ale 422 z założenia oznacza, że serwer działa zgodnie z zamierzeniem i sprzeciwia się danym, więc zbadaj samą rzeczywistą regułę walidacji, zanim założysz, że jest zepsuta.