Как правильно сопоставлять доменные ошибки с HTTP-кодами 400, 404, 409 и 500?

Как сопоставлять доменные ошибки с HTTP-кодами?

• Доменная ошибка описывает бизнес-логику, а HTTP-код относится к протоколу
• 400 (Bad Request): ошибки валидации и некорректные входные параметры
• 404 (Not Found): запрошенная сущность отсутствует в хранилище
• 409 (Conflict): нарушение бизнес-правил или конфликт текущего состояния, например уникальности
• 500 (Internal Server Error): непредвиденные системные ошибки, баги и исключения
• Для маппинга следует применять централизованный middleware или фильтр
• Клиент должен получать понятное сообщение и корректный HTTP-код REST API
• Единая стратегия облегчает отладку и помогает соблюдать API-контракт с клиентом

Развёрнутый ответ

Краткий ответ

Сопоставление доменных ошибок с HTTP-кодами — один из важных аспектов проектирования RESTful API. Благодаря ему клиент понимает результат операции и причину сбоя. HTTP-код при этом выбирают так, чтобы он как можно точнее передавал смысл соответствующей доменной ошибки.

Основные случаи

• 404 Not Found — этот статус используют, когда запрошенный ресурс отсутствует в системе. Например, клиент пытается получить пользователя по ID, которого нет в хранилище. Это типичная ситуация, связанная с отсутствием данных.
• 400 Bad Request — код уместен, если запрос составлен некорректно: данные не проходят валидацию или нарушен ожидаемый формат. В таком случае проблема находится на стороне клиента, а сервер указывает на неверные параметры запроса.
• 409 Conflict — статус предназначен для конфликтов бизнес-логики или состояния ресурса. Он подходит, например, когда создаётся ресурс с уже занятым уникальным полем, а также при нарушении правил дедупликации или ограничений состояния.
• 500 Internal Server Error — этот код следует оставлять для непредвиденных серверных сбоев: проблем инфраструктуры, таймаутов, ошибок базы данных и прочих исключений, которые не вызваны непосредственно действиями клиента.

Практическая реализация

В прикладных системах нередко создают собственную иерархию исключений: например, ResourceNotFoundException сопоставляют с 404, ValidationException — с 400, а ConflictException — с 409. Затем такие исключения перехватываются в контроллере или middleware и преобразуются в соответствующие HTTP-статусы. Это делает обработку ошибок более однозначной и упрощает сопровождение. Чтобы не получать условную ошибку «583 Unknown Error», необходимо настроить качественное логирование и описать все API-коды статусов в OpenAPI. Применение стандартных HTTP-кодов делает поведение клиента предсказуемым и ускоряет отладку.