Ошибка 422 Unprocessable Content

Что значит код 422

RFC 9110 (раздел 15.5.21): сервер понимает тип содержимого запроса, синтаксис запроса корректен, но обработать содержащиеся в нём инструкции он не может. Раньше код описывался в спецификации WebDAV (RFC 4918) под названием Unprocessable Entity; в RFC 9110 он стал общим для HTTP и получил название Unprocessable Content. Это один и тот же код.

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

{"errors": {"email": ["Неверный формат адреса"], "age": ["Должно быть не меньше 18"]}}

422 или 400

Если данные корректны, но противоречат состоянию сервера (e-mail уже занят, объект изменился), подходит 409 Conflict. Многие API используют 400 и для ошибок валидации — это допустимо, единого правила нет. Главное — отдавать понятное тело ответа.

Где встречается 422

• FastAPI отвечает 422, если тело, query-параметры или путь не прошли проверку Pydantic. В поле detail — массив ошибок с путём к полю (loc) и описанием (msg).
• Laravel отдаёт 422 при ошибке валидации, если запрос ждёт JSON (заголовок Accept: application/json), с объектами message и errors.
• Ruby on Rails по соглашению отвечает 422 (:unprocessable_entity, в новых версиях :unprocessable_content), когда модель не сохранилась из-за валидаций, и при неверном CSRF-токене формы.
• GitHub API возвращает 422 с сообщением Validation Failed, например при создании уже существующей метки или неверных параметрах запроса.

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "email"],
      "msg": "Field required",
      "input": {"name": "Иван"}
    }
  ]
}

Как исправить 422 на стороне клиента

1. Прочитайте тело ответа: в нём обычно указано, какое поле и почему не прошло проверку.
2. Сверьте запрос с документацией API: имена полей, типы, обязательность, форматы дат и чисел.
3. Проверьте заголовок Content-Type: если тело в JSON, а заголовок не application/json, сервер может не увидеть поля и сообщить, что они отсутствуют.
4. Убедитесь, что числа передаются числами, а не строками, если API строг к типам, и что вложенные объекты отправлены целиком.
5. В формах на Rails и других фреймворках с CSRF-защитой обновите страницу: устаревший токен формы тоже даёт 422.

Как отдавать 422 в своём API

import { z } from "zod";

const User = z.object({
  email: z.string().email(),
  age: z.number().int().min(18),
});

app.post("/users", (req, res) => {
  const parsed = User.safeParse(req.body);
  if (!parsed.success) {
    return res.status(422).json({ errors: parsed.error.flatten().fieldErrors });
  }
  // ...создание пользователя
});

Перечисляйте все ошибки сразу, а не по одной: клиенту не придётся отправлять запрос несколько раз. Указывайте имя поля в том же виде, в каком оно приходит в запросе, чтобы фронтенд мог подсветить нужное поле формы.

422 и SEO

Код 422 относится к API и отправке форм. Публичные страницы сайта не должны отвечать 422 на обычный GET-запрос: такие адреса не попадут в индекс. Если робот получает 422, проверьте, не срабатывает ли валидация на параметрах в URL (например, на метках utm_*), и ответ страницы проверкой кода ответа.