Stage 4. Response Status Codes

HTTP-статус — это первый и самый короткий ответ сервера о результате операции. Клиентские библиотеки, ретраи, мониторинг и алерты в первую очередь ориентируются именно на код ответа. Поэтому корректные статусы — не “косметика API”, а часть эксплуатационной надежности.

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

На практике особенно важны несколько кодов. 200 OK подходит для успешного чтения или обновления с телом ответа. 201 Created показывает, что появился новый ресурс. 204 No Content полезен, когда операция успешна, но тело не требуется. Для ошибок клиента чаще всего нужны 400, 401, 403, 404, 409, 422. Для внутренних сбоев — 500.

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

Статус должен согласовываться с телом ошибки. Если сервер возвращает 409 Conflict, тело должно объяснять конфликт состояния, а не писать абстрактное “something went wrong”. Эта связка особенно важна при интеграциях: партнёрские команды часто автоматизируют реакцию именно по паре “код + тип ошибки”.

{
  "error": "conflict",
  "message": "order already confirmed",
  "traceId": "a733ed51"
}

Отдельно нужно различать 401 и 403. 401 означает, что клиент не аутентифицирован или токен невалиден. 403 означает, что аутентификация есть, но прав недостаточно. Когда эти коды путают, клиенты неправильно строят UX: вместо запроса логина показывают “доступ запрещён” и наоборот.

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

Важно, чтобы одинаковые сценарии в разных endpoint-ах возвращали одинаковые статусы. Если один и тот же тип ошибки в одном месте даёт 409, а в другом 400, клиенту приходится писать лишние ветки обработки, а QA теряет целостную матрицу ожиданий.

Справочная таблица HTTP-статусов

Практический сценарий

В платёжном API конфликт повторной операции в одном endpoint-е возвращал 409, а в другом — 200 с полем success=false. Из-за этого мобильный клиент в части случаев считал операцию успешной и не показывал пользователю ошибку повторного платежа. После унификации статусов и error-format поведение стало предсказуемым: клиент корректно отличает успех от конфликта, а мониторинг начал показывать реальную картину проблем.