HTTP-коды состояния: что они означают и когда их использовать

Твой API возвращает 200. Тело ответа говорит {"error": "Not found"}.

Это неправильно. Коды состояния существуют не просто так. Используй их правильно.

Пять категорий

1xx — Информационные. Редко встречаются на практике.

2xx — Успех. Запрос сработал.

3xx — Перенаправление. Иди куда-то ещё.

4xx — Ошибка клиента. Ты сделал что-то неправильно.

5xx — Ошибка сервера. Мы сделали что-то неправильно.

Коды, которые ты действительно будешь использовать

Успех (2xx)

200 OK — Стандартный успех. Используй для GET-запросов, которые возвращают данные.

201 Created — Ресурс был создан. Используй после успешного POST, который что-то создаёт.

204 No Content — Успех, но нечего возвращать. Используй для DELETE или обновлений, которые не возвращают данные.

Ошибки клиента (4xx)

400 Bad Request — Некорректный запрос. Невалидный JSON, отсутствующие обязательные поля, неправильные типы данных.

401 Unauthorized — Нет аутентификации. Пользователь должен войти.

403 Forbidden — Аутентифицирован, но не разрешено. Пользователь существует, но не имеет прав.

404 Not Found — Ресурс не существует. Классика.

409 Conflict — Запрос конфликтует с текущим состоянием. Дублирующееся имя пользователя, несоответствие версий.

422 Unprocessable Entity — Синтаксически корректный, но семантически неправильный. Валидный JSON, но нарушены бизнес-правила.

429 Too Many Requests — Ограничение частоты. Притормози.

Ошибки сервера (5xx)

500 Internal Server Error — Общий сбой сервера. Что-то упало.

502 Bad Gateway — Вышестоящий сервер упал. Твой сервер в порядке, но что-то, от чего он зависит, — нет.

503 Service Unavailable — Временно недоступен. Обслуживание или перегрузка.

504 Gateway Timeout — Вышестоящий сервер не ответил вовремя.

Частые ошибки

200 с ошибкой в теле. Если это ошибка, используй код ошибки. Не заставляй клиентов парсить тело, чтобы узнать, успешно ли.

500 для ошибок валидации. Пользователь отправил плохие данные? Это 400 или 422, не 500. Сервер не сломан — запрос сломан.

Путаница 401 vs 403. 401 означает "кто ты?" 403 означает "я знаю, кто ты, но нет."

404 для всего. "Не найдено" не всегда правильный ответ. Неправильный метод? 405. Ограничение частоты? 429.

Проектирование API

Будь конкретным. Клиенты могут обрабатывать конкретные ошибки разумно. Общие ошибки означают общую обработку.

Включай детали ошибки в тело:

{
  "error": "validation_failed",
  "message": "Email format is invalid",
  "field": "email"
}

Код состояния говорит, какая категория проблемы. Тело объясняет конкретно.

Обработка кодов состояния как клиент

2xx — Парси ответ, продолжай нормально.

4xx — Твоя вина. Логируй, показывай пользователю, исправь запрос.

5xx — Вина сервера. Может быть, повтори с задержкой. Может быть, оповести.

3xx — Следуй перенаправлениям автоматически (большинство HTTP-клиентов делают это).

Не проверяй только на 200. Проверяй на успех (2xx) и обрабатывай другие случаи соответственно.

---

Коды состояния — это коммуникация. Используй их правильно, и API становятся самодокументируемыми. Неправильно используй их, и отладка становится угадыванием.