Каталог ошибок API

Норматив

Для каждого сервиса ошибки должны сопровождаться:

• HTTP-кодом;
• кратким машинно-читаемым идентификатором;
• человекочитаемым сообщением;
• условием возникновения.

Текущие типовые ошибки

Код	Контекст	Пример условия
400	ValidationError	Отсутствует обязательное поле, неверный статус, неверный формат
401	Auth required	Запрос к защищенному endpoint без токена/сессии
403	Permission denied	Нарушение роли или ownership
404	Not found	Объект/заказ/conversation не найден
500	Internal error	Необработанное исключение, сбой интеграции

Сервисные примеры

• auth_service: invalid credentials, password mismatch.
• user_service: pending seller request already exists.
• product_service: недопустимый доступ к созданию товара без seller-role.
• order_service: empty cart, invalid status transitions, missing order item.
• review_service: отсутствие подтвержденной покупки/доставки.
• chat_service: conversation id required.
• admin_service: invalid role/status values в admin actions.

События user_error (фронтенд → analytics)

При показе ошибки пользователю SPA отправляет операционное событие user_error (без зависимости от cookie consent аналитики):

Поле	Описание
incident_id	Номер для поддержки, формат KON-XXXXXXXX
error_code	Машинный код (API_VALIDATION_400_ORDERS, код бэкенда code, и т.д.)
user_id	ID пользователя, если авторизован
payload.source	api | client | network | validation
payload.user_message	Краткий текст для админ-журнала (до 200 символов)

Журнал инцидентов: админка → Аналитика → вкладка «Ошибки» → таблица «Инциденты пользователей».

Технический долг

• Формат ошибок между сервисами неоднороден (detail vs error/message/errors).
• Требуется унификация error envelope на бэкенде; фронтенд уже нормализует ответы и выдаёт incident_id.