Ошибка 422 Unprocessable Content

HTTP 422 Unprocessable Content означает: сервер понимает тип содержимого запроса, синтаксис содержимого корректен, но выполнить содержащиеся в нём инструкции не может.

Типичный пример — валидный JSON, который успешно парсится, но содержит недопустимое значение: дата окончания раньше даты начала, обязательное поле пустое, идентификатор не соответствует бизнес-правилу или комбинация параметров невозможна.

Главная ошибка при диагностике 422 — искать проблему в сети или JSON-синтаксисе, когда запрос уже дошёл до уровня семантической проверки.

Что означает HTTP 422

{
  "start_at": "2026-08-26",
  "end_at": "2026-08-20"
}

JSON синтаксически корректен, но правило:

end_at >= start_at

нарушено.

JSON parse → OK
semantic validation → FAIL
→ 422

RFC 9110 описывает 422 именно как случай, когда тип содержимого понятен, синтаксис корректен, но сервер не может обработать инструкции.

400, 409, 415 и 422

Границы в конкретном API определяет контракт. Важнее последовательность: одинаковая ошибка должна стабильно моделироваться одинаковым кодом и machine-readable reason.

Основные причины 422

Ошибка валидации поля

{
  "email": "not-an-email"
}

Нарушение диапазона

{
  "quantity": -10
}

Несогласованные поля

{
  "min": 100,
  "max": 50
}

Невозможная комбинация параметров

Каждое поле отдельно допустимо, но их сочетание нарушает правило домена.

Ссылка на объект, который нельзя использовать в этом контексте

Например, идентификатор существует, но ресурс находится в состоянии, где операция запрещена. В некоторых API это будет 422, в других — 409. Нужно смотреть контракт.

Шаг 1. Сохраните полный HTTP-ответ

curl -i   -H 'Content-Type: application/json'   --data-binary @request.json   https://api.example.com/v1/orders

Полезный ответ API:

{
  "error": "validation_failed",
  "fields": {
    "end_at": "must_not_be_before_start_at"
  }
}

Клиенту нужен стабильный machine-readable код. Детальная внутренняя информация при этом не должна раскрывать секреты или структуру БД.

Шаг 2. Убедитесь, что JSON действительно корректен

jq . request.json

Если jq не может разобрать файл, сначала исправьте синтаксис. Такой сценарий ближе к 400, а не к 422.

Шаг 3. Проверьте Content-Type

Content-Type: application/json

Если endpoint ожидает JSON, а клиент отправляет другой media type, более точной ошибкой может быть 415.

Шаг 4. Сократите запрос до минимального

Начните с минимально допустимого payload и добавляйте поля постепенно:

минимальный valid request → success
+ поле A                  → success
+ поле B                  → 422

Так можно быстро локализовать конкретное значение или комбинацию.

Шаг 5. Сверьте схему и бизнес-правила

Проверьте:

• required fields;
• типы;
• enum values;
• min/max;
• формат дат;
• timezone;
• взаимозависимые поля;
• состояние связанного ресурса;
• ограничения текущего пользователя.

Не пытайтесь исправить 422 случайным удалением полей: сначала поймите, какое правило нарушено.

Шаг 6. Проверьте client/server version

После релиза frontend может отправлять новое enum value, которое старый backend ещё не понимает.

При rolling deployment возможен неприятный симптом:

backend A → принимает значение
backend B → 422

Тогда одна и та же операция ведёт себя нестабильно.

Шаг 7. Сопоставьте request ID и логи

В логах полезно иметь:

request_id
endpoint
validation_error_code
field
actor
version

Не логируйте пароль, токен или полный чувствительный body только ради расследования.

422 в формах

Для пользовательской формы 422 полезен, если frontend может привязать server-side validation error к конкретному полю.

Например:

{
  "errors": [
    {
      "field": "email",
      "code": "already_used"
    }
  ]
}

Но already_used иногда логичнее моделировать 409 — это зависит от контракта ресурса.

422 после изменения бизнес-правила

Если после deployment резко выросло число 422:

1. сравните версии клиента и сервера;
2. проверьте migrations/reference data;
3. проверьте enum;
4. проверьте timezone/date parsing;
5. проверьте feature flags;
6. сравните конкретные validation error codes до и после релиза.

Рост 422 может означать как дефект, так и корректное отклонение новых неправильных данных.

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

Нужны минимум два сценария:

валидный payload   → 200/201/204
невалидный payload → 422 с ожидаемым error code

Если оба запроса после исправления проходят, validation могла быть случайно отключена.

422 и автоматический мониторинг

Нельзя считать любой 422 признаком падения API. Если монитор отправляет заведомо невалидные данные, 422 может быть правильным expected result.

Для проверки работоспособности выбирайте безопасный валидный запрос и проверяйте HTTP status, latency, JSON и бизнес-критерий.

UpWatch можно использовать для регулярной проверки API endpoint, если request и ожидаемый результат соответствуют реальному контракту.

Типичные ошибки

• путать 422 со сломанным JSON;
• исправлять сеть при семантической ошибке;
• отдавать только текст без machine-readable reason;
• возвращать 200 с {"error": ...} вместо нормального контракта;
• отключать validation ради устранения 422;
• считать каждый 422 инцидентом инфраструктуры.

Практический чек-лист

1. Подтвердить HTTP 422.
2. Сохранить response body.
3. Проверить JSON-синтаксис.
4. Проверить Content-Type.
5. Найти machine-readable reason.
6. Сократить payload.
7. Сверить схему.
8. Проверить бизнес-правила.
9. Сравнить версии клиента/backend.
10. Сопоставить request ID и logs.
11. Проверить valid и invalid сценарии после исправления.
12. Не отключать полезную validation.

Источники и спецификации

• RFC 9110: 422 Unprocessable Content
• RFC 9110: 400 Bad Request
• RFC 9110: 415 Unsupported Media Type
• curl: официальная документация