Какой статус код HTTP-запроса возвращается, когда в теле result == false и описание ошибки?

Статус HTTP кода при result == false в ответе API

Короткий ответ: Нет универсального или предопределённого статуса кода HTTP, который автоматически возвращается при result == false в теле ответа. Статус код определяется соглашениями и бизнес-логикой конкретного API.

Основное правило: HTTP статус код (200, 400, 500, etc.) и тело ответа (JSON с полями result, errorDescription) — это два разных уровня информации в ответе сервера.

Разделение ответственности: статус код и тело ответа

1. HTTP статус код (например, 200 OK, 400 Bad Request) — это протокольный уровень. Он сообщает клиенту (браузеру, другому сервису) общее состояние запроса: успех, ошибка клиента, ошибка сервера, отсутствие ресурса.
2. Тело ответа (Body) — это бизнес-логический уровень. В формате JSON (или другого) оно содержит детализированные данные, специфичные для вашего приложения: результат операции (result: true/false), данные объекта, описание ошибки (errorDescription: "Неверный формат email").

Типичные паттерны и практики

В современной разработке RESTful или RPC API распространены следующие подходы:

Паттерн 1: Статус 200 OK с детальной ошибкой в теле

Самый распространённый подход для бизнес-логических ошибок (не связанных с валидацией или синтаксисом запроса).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": false,
  "errorDescription": "Пользователь с таким email уже существует.",
  "errorCode": "USER_DUPLICATE"
}

• Логика: Сам HTTP запрос был технически успешен (правильный URL, метод, заголовки, тело). Поэтому статус 200 OK. Однако бизнес-логика сервиса не позволила выполнить операцию (например, дублирование email при регистрации). Эта ошибка передаётся в теле.
• Преимущества: Клиент всегда получает структурированный JSON. Легко обрабатывать единообразно.
• Недостатки: Может нарушать строгие принципы REST, где статус код должен точно отражать результат.

Паттерн 2: Статус 4xx для ошибок клиента + тело с детализацией

Часто используется для ошибок валидации входных данных.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "result": false,
  "errorDescription": "Поле 'email' не соответствует формату.",
  "validationErrors": [
    {"field": "email", "message": "Must be a valid email address"}
  ]
}

• Логика: Запрос клиента был некорректен (невалидные данные). Статус 400 указывает на это на уровне протокола. Тело расширяет информацию, помогая клиенту понять, что именно исправить.
• Стандарт Problem Details for HTTP APIs (RFC 7807): Многие API используют стандартизированный формат для ошибок.

  HTTP/1.1 422 Unprocessable Entity
  Content-Type: application/problem+json
  
  {
    "type": "https://api.example.com/errors/validation",
    "title": "Validation Error",
    "status": 422,
    "detail": "Поле 'email' не соответствует формату.",
    "instance": "/users/register"
  }
  

Паттерн 3: Статус 5xx для внутренних ошибок сервера

Когда result == false из-за сбоя на сервере (база данных недоступна, внешний сервис не отвечает).

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "result": false,
  "errorDescription": "Внутренняя ошибка сервиса. Попробуйте позже.",
  "timestamp": "2024-05-20T12:00:00Z"
}

• Логика: Сервер не смог выполнить запрос по внутренним причинам. Статус 500 сигнализирует клиенту о серьёзной проблеме. Тело может содержать общее описание, но без деталей (для безопасности).

Ключевые рекомендации по дизайну API

• Консистентность (Consistency) — самое важное. Внутри одного API должен быть единый подход. Нельзя в одном endpoint возвращать 200 при result == false, а в другом — 400. Это сбивает клиентов с толку.
• Документируйте вашу схему. В документации API (Swagger/OpenAPI) четко укажите:

    *   Какой HTTP статус код возвращается для успеха (`result == true`).
    *   Какой HTTP статус код возвращается для ошибок (`result == false`).
    *   Структуру тела ответа для обоих случаев.

• Используйте поле result как флаг успеха операции, а статус код — как флаг успеха запроса. Это разделение часто удобно для клиентской логики.
• Для ошибок валидации предпочтительны 400 Bad Request или 422 Unprocessable Entity. Это позволяет клиентам (и промежуточным инструментам) быстро классифицировать проблему.
• Включайте в тело не только errorDescription, но и уникальный errorCode (строка) для машинной обработки. Это позволяет клиенту точно определить тип ошибки, даже если текст описания меняется.

Итог: Ответ на ваш вопрос зависит исключительно от внутреннего дизайна и соглашений конкретного API. Наиболее частый и прагматичный вариант в реальных проектах — 200 OK с детализированной бизнес-ошибкой в теле JSON, так как это обеспечивает единообразную структуру ответов и упрощает обработку на клиенте. Однако для строгого REST или публичных API часто выбирают подход с использованием соответствующих статус кодов 4xx или 5xx.