HTTP 422 Unprocessable Entity: запрос понятен, но данные не приняты

Код 422 применяют, когда запрос по форме верен, а сервер всё равно не может его обработать из-за смысловых ошибок в данных. Формат правильный, JSON разбирается, но значения не проходят проверку: адрес почты записан неверно, дата из будущего там, где нужна прошедшая, поле, которое должно быть числом, содержит текст.

Это отличает 422 от 400, где ломается сам синтаксис или структура запроса. Здесь структура в порядке, не подходит содержание. Код возник в расширениях протокола и получил широкое распространение в интерфейсах программ и веб-фреймворков.

Чаще всего он появляется в веб-формах и приложениях при регистрации, оформлении заявки, сохранении профиля. Сервер проверяет поля и возвращает список ошибок: короткий пароль, занятое имя, неверный формат телефона.

Если на странице сообщение не показано, ошибку часто можно увидеть в инструментах разработчика браузера: в теле ответа лежит перечень проблемных полей. Второй распространённый источник — программные интерфейсы: разработчик отправляет корректный JSON, но с недопустимыми значениями, отсутствием обязательных полей или нарушением связей между ними.

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

Если форма сложная, отправляйте её частями либо сначала с минимальным набором данных, затем добавляйте остальное. Так проще выявить, какое именно значение вызывает отказ. Используйте другой браузер или приватное окно, чтобы исключить влияние автозаполнения, подставившего устаревшие значения.

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

Если ошибка появляется у всех, а поля заполнены разумно, вероятна поломка на стороне сервиса, например после обновления правил проверки. Сообщите в поддержку время, действие и текст ошибки. Скриншот с телом ответа из инструментов разработчика сильно ускорит разбор.

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

Вторая — ограничения длины и набора символов. Поле имени может не принимать цифры и знаки, пароль — требовать разные регистры и цифры, комментарий — превышать допустимую длину. Сообщение об этом иногда скрыто мелким шрифтом под полем.

Третья — зависимости между полями. Дата окончания раньше даты начала, страна не соответствует коду региона, сумма частей не равна общей сумме. Такие ошибки трудно заметить, потому что каждое поле само по себе допустимо. Если сервис не показывает причину, попробуйте изменить одно поле за раз. Систематическая проверка почти всегда находит виновника быстрее, чем повторные отправки одной и той же формы подряд.

Возвращайте вместе с 422 структурированный список ошибок с именем поля и кратким текстом, чтобы интерфейс мог подсветить нужное место. Не смешивайте 400 и 422 произвольно: договоритесь в команде, что первый означает нарушение формата, а второй смысловую ошибку. Проверяйте данные и на клиенте, и на сервере: клиентская проверка удобна, серверная обязательна.

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