Системный анализ — это не только про требования и диаграммы. Это ещё и про здравый смысл, который ты закладываешь в интерфейсы. Даже такие “мелочи”, как HTTP-коды ошибок, — это часть проектирования.
Если API возвращает «всё по 200», от этого страдают и разработчики, и бизнес.
Разберёмся, какие ошибки когда использовать, чтобы твой API был понятным и предсказуемым.
🟥 400 — Bad Request
Что это: клиент прислал что-то не то.
Когда использовать:
- некорректный JSON или структура тела запроса;
- нарушен формат (например, email без @);
- отсутствует обязательный параметр.
📌 Это не ошибка сервера. Это ошибка клиента. Валидация должна отловить её до бизнес-логики.
🔒 401 — Unauthorized
Что это: пользователь не авторизован.
Когда использовать:
- не передан токен;
- токен просрочен или неверный.
📌 Здесь важно: пользователь ещё не в системе. Он не доказал, кто он.
🚫 403 — Forbidden
Что это: авторизация есть, но прав нет.
Когда использовать:
- пользователь вошёл, но пытается сделать то, что ему не разрешено;
- доступ к ресурсу ограничен по ролям или правам.
📌 Частая ошибка — путать 401 и 403.
Запомни: 401 — «не знаю кто ты», 403 — «знаю, но нельзя».
🔍 404 — Not Found
Что это: запрошенного ресурса нет.
Когда использовать:
- id в URL ссылается на несуществующий объект;
- путь неправильный (в разумных пределах).
📌 Не считается ошибкой запроса — просто данных нет.
⚠️ 409 — Conflict
Что это: конфликт бизнес-логики.
Когда использовать:
- при попытке создать уже существующий объект (например, email занят);
- при конфликте версий (concurrent modification, optimistic lock).
📌 Отличается от 400 — формат и структура верные, но логика не проходит.
💥 500 — Internal Server Error
Что это: что-то пошло не так на сервере.
Когда использовать:
- при исключениях;
- при ошибках, которые не зависят от клиента.
📌 Используй осторожно. Не превращай все ошибки в 500. Это сигнал аварии, не бизнес-кейс.
💤 503 — Service Unavailable
Что это: сервер временно не может обработать запрос.
Когда использовать:
- сервис недоступен (перезапуск, перегрузка);
- зависимые компоненты не отвечают.
📌 Можно использовать с Retry-After в заголовке — подсказать, когда повторить.
✅ Зачем это всё?
HTTP-код — это первое, что видит клиент при ошибке.
Он должен быть:
- точным — чтобы понимать, что пошло не так;
- предсказуемым — чтобы писать стабильные клиенты;
- конкретным — чтобы логировать и алертить правильно.
Проектируя ошибки — ты проектируешь опыт использования.
🔗 Ранее по теме
Хочешь освежить в памяти, что означают группы ошибок (1xx, 2xx, 3xx, 4xx, 5xx) и откуда вообще берутся все эти 503 и 404?