422 Unprocessable Entity: що означає і як виправити

Що означає 422 Unprocessable Entity

422 виник у WebDAV (RFC 4918) і пізніше був широко прийнятий REST API як стандартна відповідь для збоїв семантичної валідації. RFC 9110 формально перейменував текст статусу на 422 Unprocessable Content, прибравши специфічне для WebDAV слово "Entity", хоча обидві назви описують ідентичний код статусу, і "Unprocessable Entity" лишається значно поширенішою міткою в значеннях за замовчуванням фреймворків і документації API. Відмінність, що має значення, - синтаксис проти семантики: JSON розібрався правильно, кожен тип обов'язкового поля збігається, і запит правильно сформований за кожним структурним правилом, але значення всередині нього порушує бізнес-правило, наприклад адреса електронної пошти в неправильному форматі, дата в минулому там, де потрібна майбутня, чи поле, що посилається на запис, якого не існує.

Як з'являється помилка

422 майже ніколи не з'являється як помилка навігації браузера, оскільки це переважно відповідь API, а не щось, що прямо викликає посилання чи відправлення форми; вона з'являється у вкладці мережі, спливному повідомленні про помилку чи провалених твердженнях тесту. З командного рядка корисна деталь лежить у тілі відповіді:

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"]}}

Більшість добре побудованих API повертають структуроване тіло помилки разом із 422, точно називаючи, яке поле провалилося і чому, а не лишають викликачу гадати лише за кодом статусу.

Що спричиняє 422 Unprocessable Entity

• Помилки валідації в REST API. Застосунки на Rails зазвичай автоматично повертають 422, коли модель ActiveRecord провалює валідацію при створенні чи оновленні. Валідація форм-запитів у Laravel за замовчуванням повертає 422 для провалених правил. FastAPI, побудований на Pydantic, повертає 422 щоразу, коли дані запиту провалюють перевірку типу чи обмеження моделі Pydantic, тому це один із найчастіше зустрічних кодів статусу саме в проєктах FastAPI.
• Поле з правильним типом, але недійсним значенням. Рядок там, де очікувався рядок, але такий, що провалює перевірку формату, ліміт довжини чи список дозволених значень.
• Посилання на щось, чого не існує. Зовнішній ключ, ідентифікатор користувача чи slug у тілі запиту, синтаксично нормальний, але не відповідає жодному справжньому запису.
• Бізнес-правила поза простою валідацією полів. Код знижки, синтаксично валідний, але прострочений, чи кількість, що є валідним цілим числом, але перевищує наявний запас.
• Повністю відсутнє обов'язкове поле. Залежно від фреймворку, відсутнє обов'язкове поле може повернути 422, а не 400, оскільки запит парситься нормально, йому просто бракує значення, яке вимагає шар валідації.

422 проти 400

Межа - синтаксис проти семантики. 400 Bad Request означає, що сервер узагалі не зміг розібрати запит, наприклад через зіпсований JSON чи тіло, невалідне за жодним структурним правилом. 422 означає, що запит розібрався без жодних проблем, і кожне поле правильного типу, але значення всередині нього провалює правило, яке застосунок перевіряє вже після розбору. На практиці багато API розмивають цю відмінність і використовують 400 для обох випадків, що виправдано, але менш точно; клієнт, що інтегрується з API, має читати тіло відповіді, а не покладатися лише на код статусу, щоб точно знати, що саме провалилося.

Як виправити помилку 422

Якщо ви клієнт, що викликає API

1. Читайте тіло відповіді, а не лише код статусу. Відповідь 422 у добре побудованому API називає конкретне поле й правило, що провалилося, що точно каже, що виправити, без подальших здогадок.
2. Звірте поле з документованими обмеженнями API, такими як формат, довжина й дозволені значення, оскільки це бізнес-правила, яких сама схема вам не покаже.
3. Ставтеся до 422 як до сигналу виправити дані, а не повторювати запит без змін. Повторення незміненого запиту, що провалив валідацію, щоразу провалюватиметься ідентично; коректно поведений клієнт має показати конкретну помилку користувачу, а не мовчки повторювати спроби.

Якщо ви керуєте API

1. Завжди повертайте структуроване тіло помилки разом із 422, називаючи поле й правило, що провалилося, а не голий код статусу без пояснення.
2. Тримайте повідомлення про помилки валідації конкретними й дієвими, наприклад "email must be a valid address" замість загального "validation failed", що змушує викликача гадати, яке з кількох полів було проблемою.
3. Свідомо визначтеся між 400 і 422 для свого API й задокументуйте цей вибір, щоб інтегратори могли побудувати надійну обробку помилок, а не ставитися до кожного 4xx однаково.
4. Логуйте перевірені, але відхилені тіла запитів під час розробки, щоб виявляти випадки, коли ваш власний клієнтський код надсилає дані, що стабільно провалюють валідацію, що часто вказує на невідповідність між клієнтом і фактичними правилами API.

Як клієнту обробляти відповідь 422

Добре спроєктований клієнт ставиться до 422 як до принципово відмінного від помилки 5xx чи мережевого збою: це означає, що сервер здоровий і працює правильно, а викликач надіслав щось, що сервер ніколи не прийме як є. Правильна реакція - розібрати тіло помилки, зіставити кожне провалене поле назад з формою чи введенням, що його спричинило, і показати користувачу щось дієве, а не повторювати спробу з відкладенням, як ви робили б для тайм-ауту чи 503. Автоматизовані тести, що перевіряють шар валідації API, мають перевіряти конкретне повернуте тіло помилки, а не лише код статусу 422, оскільки саме це підтверджує правильність самої логіки валідації.

Як запобігти непоміченим 422

Правило валідації, що несподівано змінилося, чи то через деплой, оновлення стороньої бібліотеки, чи міграцію схеми, може непомітно почати відхиляти запити, які раніше проходили успішно. HTTP-перевірка, що надсилає завідомо коректне тіло запиту й перевіряє очікуваний код статусу, ловить таку регресію одразу після деплою. Для API з кількома ендпоінтами чи тілом, яке сам код статусу не може повністю перевірити, API-моніторинг, що також перевіряє тіло відповіді, підтверджує саму логіку валідації, а не лише те, що сервер досяжний.

Пов'язані помилки

Дивіться 400 Bad Request для випадку, коли запит узагалі не розбирається, з яким контрастує цей посібник, огляд 4xx для ширшої родини, і 401 Unauthorized та 405 Method Not Allowed деінде в цій партії.

Часті запитання

Чи 422 Unprocessable Entity - те саме, що 422 Unprocessable Content?

Так. RFC 9110 перейменував пояснювальну фразу на Unprocessable Content, але це той самий код статусу з тим самим значенням; більшість фреймворків і документації API досі використовують старіше формулювання Unprocessable Entity.

Чому мій застосунок на FastAPI повертає 422 для відсутнього поля?

FastAPI автоматично перевіряє дані запиту проти ваших моделей Pydantic, і відсутнє обов'язкове поле, чи поле неправильного типу, провалює цю валідацію й повертає 422 з тілом, що описує точно, яке поле і правило провалилося.

Чи варто повторювати запит, що отримав 422?

Лише після зміни даних, що провалили валідацію. Повторення ідентичного запиту щоразу видасть ідентичний 422, оскільки сервер правильно й стабільно відхиляє те саме недійсне введення.

Яка різниця між 422 і 400 на практиці?

400 - для запиту, який сервер узагалі не може розібрати. 422 - для запиту, що розбирається нормально, але містить значення, яке провалює правило валідації чи бізнес-правило. Багато реальних API використовують 400 для обох випадків, тож завжди перевіряйте задокументовану конвенцію конкретного API, який ви викликаєте.

Чи може 422 означати, що в сервера є баг?

Може, якщо саме правило валідації неправильне, наприклад відхиляє справді валідний формат електронної пошти. Але 422 за задумом означає, що сервер працює як задумано й заперечує проти даних, тож досліджуйте фактичне правило валідації, перш ніж припускати, що воно зламане.