Что такое статус-код 422?

Что такое статус-код 422 Unprocessable Entity?

Статус-код 422 Unprocessable Entity — это код состояния HTTP из протокола WebDAV (расширение HTTP для распределённой работы с файлами), который был официально принят в спецификации RFC 4918. На практике он широко используется в современных RESTful API, особенно построенных на принципах семантической валидации. В отличие от более известных кодов ошибок, таких как 400 Bad Request (общая ошибка клиента) или 404 Not Found (ресурс отсутствует), 422 имеет специфическую и важную семантику.

Семантика и предназначение статуса 422

Ключевая идея 422 Unprocessable Entity заключается в том, что запрос клиента синтаксически корректен (т.е., он соответствует ожидаемому формату — корректный JSON, XML, структура заголовков), сервер его принял и попытался обработать, но не может выполнить из-за семантических (логических) ошибок в данных. Другими словами, сервер "понял" запрос, но не может с ним работать из-за проблем в содержании.

Типичные сценарии использования:

• Валидация бизнес-логики: Например, попытка создать заказ с несуществующим product_id или отправить заявку с датой окончания раньше даты начала.
• Нарушение уникальности: Регистрация пользователя с уже занятым email-адресом.
• Неверные ссылки (foreign key constraints): В REST API — создание комментария к несуществующей статье.
• Некорректные форматы данных внутри корректной структуры: Передача строки вместо числа в поле age, но в правильно сформированном JSON-объекте.
• Несоответствие ожидаемым Enum-значениям: Передача статуса completed вместо допустимых pending, in_progress.

Почему 422, а не 400?

Использование 422 вместо общего 400 Bad Request — это лучшая практика проектирования API, так как она даёт клиенту более точную и полезную информацию для исправления ошибки. Клиент понимает, что проблема не в синтаксисе запроса (не нужно проверять JSON на запятые или заголовки), а именно в переданных значениях. Это упрощает отладку на стороне клиента и улучшает пользовательский опыт (UX), позволяя показывать более точные сообщения об ошибках рядом с конкретными полями формы.

Ответ сервера при 422

Сервер обязан вернуть в теле ответа детализированное описание ошибок, обычно в формате JSON. Это позволяет клиенту программно обработать ошибки и показать их пользователю.

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Пользователь с таким email уже существует."
    },
    {
      "field": "birth_date",
      "message": "Дата рождения не может быть в будущем."
    }
  ]
}

Практическое значение для QA Engineer

Понимание статуса 422 критически важно для инженера по качеству по нескольким причинам:

1. Проектирование тестов: При тестировании API необходимо отдельно покрывать тестами сценарии, которые должны возвращать 422. Это не просто "ошибка 4xx", а целый класс проверок бизнес-валидации.
2. Анализ логов и баг-репортов: Умение быстро идентифицировать 422 в логах или инструментах мониторинга (например, Kibana, Grafana) позволяет сразу сузить круг поиска проблемы до логики валидации данных на стороне сервера, а не проблем с сетью или инфраструктурой.
3. Чёткие баг-репорты: В отчёте об ошибке можно точно указать: "При отправке запроса POST /api/v1/users с корректным JSON, но с email: 'duplicate@example.com', сервер возвращает 422 Unprocessable Entity с ожидаемым сообщением об ошибке уникальности. Фактический ответ: {...}".
4. Валидация ответов: Необходимо проверять не только факт возврата кода 422, но и:

    *   **Структуру тела ответа** на соответствие контракту API (согласно документации или OpenAPI-спецификации).
    *   **Корректность и точность сообщений об ошибках** для каждого проблемного поля.
    *   **Не возвращается ли по ошибке `400` или `500`** в ситуациях, где ожидается семантическая ошибка (`422`).

Пример теста на Python (с использованием pytest и requests):

import pytest
import requests

BASE_URL = "https://api.example.com/v1"

def test_create_user_validation_duplicate_email():
    """Тест на возврат статуса 422 при попытке создать пользователя с существующим email."""
    existing_user_data = {"email": "existing@test.com", "name": "Test User"}
    duplicate_user_data = {"email": "existing@test.com", "name": "Another User"}

    # Предусловие: создаём первого пользователя
    requests.post(f"{BASE_URL}/users", json=existing_user_data)

    # Действие: пытаемся создать второго с тем же email
    response = requests.post(f"{BASE_URL}/users", json=duplicate_user_data)

    # Проверки
    assert response.status_code == 422, f"Ожидался статус 422, получен {response.status_code}"
    
    error_response = response.json()
    assert "errors" in error_response
    assert any(error["field"] == "email" for error in error_response["errors"]), \
           "В ответе отсутствует ошибка для поля 'email'"

Заключение

422 Unprocessable Entity — это важный инструмент в арсенале разработчиков и тестировщиков для создания понятных и отказоустойчивых API. Для QA Engineer его понимание напрямую влияет на качество тест-кейсов, глубину проверок валидации и эффективность взаимодействия с командой разработки при анализе дефектов. Использование этого статуса соответствует принципам REST, делая API более семантически строгим и удобным для потребителей.