← Все статьи

Коды ошибок REST API: как выбрать между 400, 409 и 422

· 7 мин чтения

Разбираем критерии выбора HTTP-статусов 400, 409 и 422 для REST API. Таблица условий, примеры OpenAPI 3.0 и разбор типовых ошибок валидации для точной обработки клиентскими приложениями.

При разработке REST API разработчики часто сталкиваются с вопросом: какой код ошибки вернуть, если запрос сформирован правильно, но данные невалидны? В документации RFC 9110 чёткое разграничение между 400, 409 и 422 отсутствует, что приводит к хаосу в интерфейсах. Клиенты не знают, как обрабатывать отказы, а тестировщики получают непредсказуемое поведение. Эта статья устанавливает однозначные критерии выбора статуса на основе природы ошибки.

Суть различий между 400, 409 и 422

Все три кода относятся к классу 4xx (ошибка клиента), но описывают разные стадии обработки запроса. 400 Bad Request означает, что сервер не смог понять запрос из-за синтаксической ошибки: неверный JSON, отсутствие обязательных параметров, нарушение формата даты. Сервер даже не приступает к проверке бизнес-логики. 409 Conflict возникает, когда запрос синтаксически корректен, но конфликтует с текущим состоянием ресурса: попытка создать объект с уникальным именем, которое уже занято, или обновление ресурса с устаревшей версией. 422 Unprocessable Entity используется, когда тело запроса синтаксически валидно, но содержит семантические ошибки, которые невозможно исправить простым повторением: например, сумма платежа превышает лимит, установленный правилами бизнеса, или дата рождения указывает на возраст меньше 18 лет для данного типа услуги.

В учебном профиле 400 используется для неправильного разбора или структуры запроса, 409 — для конфликта с текущим состоянием, 422 — для выбранных содержательных ошибок допустимого представления. Это согласованная политика API, а не обязательное распределение всех ошибок в любом приложении. Клиент определяет действие также по машинному коду тела, поскольку один HTTP-статус не выражает все причины.

Таблица условий применения

Для быстрого выбора кода используйте следующую таблицу. Она основана на анализе RFC 9110 и лучших практик крупных платформ:

КодУсловие возвратаТипичный примерДействие клиента
400Синтаксическая ошибка: битый JSON, отсутствующий параметр, неверный тип данныхПоле email передано как числоПроверить формат запроса, исправить структуру
409Конфликт состояния: уникальный ключ занят, версия ресурса устарелаEmail уже зарегистрированИзменить данные или обновить ETag
422Семантическая ошибка: данные валидны структурно, но нарушают бизнес-правилаВозраст пользователя меньше 18 летИзменить значения полей, соблюдая правила

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

Практический пример: создание заказа

Рассмотрим эндпоинт POST /orders. Клиент отправляет JSON с полями customer_id, items и total_amount. Разберём три сценария отказа.

Сценарий 1: Синтаксическая ошибка. Клиент присылает поле total_amount как строку "100.50" вместо числа. Фреймворк не может преобразовать значение в ожидаемый тип. Ответ: 400 Bad Request с сообщением "Field 'total_amount' must be a number". Клиент понимает, что он ошибся в структуре данных.

Сценарий 2: Конфликт состояния. Клиент пытается создать заказ для customer_id=123, но этот ID не существует в системе клиентов. Или, например, клиент пытается зарезервировать товар, который уже был продан другим покупателем. Ответ: 409 Conflict с сообщением "Customer with id 123 not found" или "Item stock is insufficient". Клиент понимает, что данные корректны, но мир изменился.

Сценарий 3: Семантическая ошибка. Клиент отправляет корректные типы данных, существующий customer_id и достаточный остаток товара. Однако total_amount равно 0, хотя минимальная сумма заказа по правилам бизнеса составляет 100 рублей. Ответ: 422 Unprocessable Entity с сообщением "Total amount must be at least 100". Клиент понимает, что структура верна, но значения не соответствуют бизнес-логике.

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

Спецификация OpenAPI 3.0

В OpenAPI 3.0 каждый код ошибки должен быть явно объявлен в секции responses. Важно не просто указать код, но и описать схему тела ответа. Для 400, 409 и 422 рекомендуется использовать единую схему ошибки, чтобы клиенты могли предсказуемо парсить ответы.

paths:
  /orders:
    post:
      responses:
        '400':
          description: Syntax error in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict with current resource state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: VALIDATION_FAILED
        message:
          type: string
          example: Total amount must be at least 100
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              reason:
                type: string

Обратите внимание на поле details. Оно позволяет передать массив конкретных проблем. Например, если две поля нарушают правила, клиент получает оба сообщения в одном ответе. Это особенно полезно для 422, где может быть несколько семантических нарушений одновременно.

Типичные ошибки в выборе кодов

Даже опытные команды допускают следующие частые ошибки:

  • Использование 400 для всех ошибок валидации. Это самая распространенная ошибка. Если клиент получил 400, он ожидает синтаксическую проблему. Когда реальная причина — бизнес-правило, клиент тратит время на поиск несуществующих синтаксических ошибок.
  • Использование 409 для не найденного ресурса. Если ресурс с данным ID не существует, это не конфликт, а отсутствие объекта. Корректный код — 404 Not Found. 409 следует использовать только для ситуаций, когда объект существует, но находится в состоянии, препятствующем операции (занят, заблокирован, изменен).
  • Использование 422 для ошибок авторизации. Проблемы с токеном или правами доступа должны возвращать 401 Unauthorized или 403 Forbidden. Смешивание этих кодов с 422 затрудняет автоматическую обработку сессий.
  • Отсутствие детализации в теле ответа. Возврат только текста "Validation failed" без указания конкретного поля бесполезен. Клиент должен знать, какое именно поле и почему отклонено.

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

Для проверки правильности использования кодов создайте набор интеграционных тестов. Каждый тест должен имитировать один из трех типов ошибок и проверять не только статус-код, но и наличие поля message в JSON-ответе.

Пример проверки для 422:

def test_order_creation_semantic_error():
    payload = {
        "customer_id": 1,
        "items": [{"sku": "ABC", "quantity": 1}],
        "total_amount": 0  # Нарушение бизнес-правила
    }
    response = client.post("/orders", json=payload)
    assert response.status_code == 422
    data = response.json()
    assert "details" in data
    assert any(d["field"] == "total_amount" for d in data["details"])

Аналогичные тесты проверяют выбранные случаи 400 и 409. Они помогают обнаружить изменение согласованного поведения, но не гарантируют отсутствие всех будущих ошибок. Для каждого случая сохраняют допустимый вход, состояние сервера и ожидаемый машинный код.

Ограничения и нюансы

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

Также помните, что 422 не является частью исходного RFC 2616, а был добавлен позже. Некоторые очень старые клиенты могут не распознавать этот код. Если поддержка таких клиентов критична, рассмотрите возможность использования 400 с подробным описанием причины в теле ответа, но это компромисс, который снижает ясность интерфейса.

Итог

Выбор между 400, 409 и 422 определяется природой ошибки: синтаксис, состояние или семантика. Чёткое соблюдение этой классификации делает API предсказуемым для клиентов и упрощает отладку. Используйте таблицу выше как чек-лист при проектировании эндпоинтов, опишите все три кода в спецификации OpenAPI и покрыть их интеграционными тестами. Это инвестиция, которая окупается снижением количества багов и вопросов от фронтенд-разработчиков.

Подробнее о принципах проектирования REST API читайте в статье REST vs SOAP. Для описания ваших эндпоинтов используйте редактор OpenAPI.