Таксономия ошибок для бизнес-приложений помогает классифицировать валидацию, auth, лимиты и сбои зависимостей, чтобы алерты и поведение UI были согласованными.
Таксономия ошибок — это общий способ называть и группировать ошибки, чтобы все обрабатывали их одинаково. Вместо того чтобы каждый экран и API придумывали свои сообщения, вы определяете небольшой набор категорий (например, validation или auth) и правила, как они показываются пользователям и в мониторинге.
Без общей структуры одна и та же проблема проявляется в разных формах. Отсутствие обязательного поля может отображаться как «Bad Request» в мобильном приложении, «Что-то пошло не так» в вебе и как стек-трейс в логах. Пользователи не понимают, что делать дальше, а дежурные тратят время, пытаясь угадать: это ошибка пользователя, атака или сбой.
Цель — согласованность: один и тот же тип ошибки приводит к одинаковому поведению UI и одинаковому поведению алертов. Ошибки валидации должны указывать на конкретное поле. Проблемы с правами должны останавливать действие и объяснять, какого доступа не хватает. Сбои зависимостей должны предлагать безопасную повторную попытку, а мониторинг — включать нужное оповещение.
Реалистичный пример: менеджер по продажам пытается создать карточку клиента, но платёжный сервис не работает. Если приложение возвращает общий 500, они будут пытаться снова и позже могут создать дубликаты. С чёткой категорией «dependency failure» UI может сообщить, что сервис временно недоступен, предотвратить повторную отправку и мониторинг пропейджит нужную команду.
Такое выравнивание важно особенно когда один бэкенд обслуживает несколько клиентов. Если API, веб, мобильное и внутренние инструменты пользуются одними и теми же категориями и кодами, сбои перестают казаться случайными.
Таксономии проще поддерживать, когда вы разделяете четыре вещи, которые часто смешивают: категория (какая это проблема), код (стабильный идентификатор), сообщение (текст для человека) и детали (структурированный контекст). HTTP-статус по-прежнему важен, но не должен быть всей историей.
Категория отвечает на вопрос: «Как должны вести себя UI и мониторинг?» Один и тот же 403 в одном месте может значить «auth», а в другом — «policy», если вы добавите правила. Категория про поведение, не про транспорт.
Код отвечает: «Что именно произошло?» Коды должны быть стабильными и скучными. Если вы переименовали кнопку или рефакторили сервис, код не должен меняться. Дашборды, алерты и скрипты поддержки зависят от этого.
Сообщение отвечает: «Что мы говорим человеку?» Решите, для кого это сообщение. Для пользователя сообщение должно быть коротким и дружелюбным. Для поддержки — с шагами дальше. Логи могут быть более техническими.
Детали отвечают: «Что нужно чтобы починить?» Держите детали структурированными, чтобы UI мог на них реагировать. Для ошибки формы это могут быть имена полей. Для сбоя зависимости — имя upstream-сервиса и значение retry-after.
Вот компактная форма, которую используют многие команды:
{
"category": "validation",
"code": "CUSTOMER_EMAIL_INVALID",
"message": "Enter a valid email address.",
"details": { "field": "email", "rule": "email" }
}
По мере развития фич держите категории маленькими и стабильными, а для новых ситуаций добавляйте новые коды, а не переиспользуйте старые. Это сохраняет поведение UI, тренды мониторинга и инструкции поддержки надёжными.
Большинство бизнес-приложений может начать с четырёх категорий, которые встречаются повсюду. Если вы назовёте их и будете одинаково обрабатывать в бэкенде, вебе и мобильных клиентах, UI сможет реагировать предсказуемо, а мониторинг станет читабельным.
Ошибки валидации происходят, когда ввод пользователя или бизнес-правило не проходят проверку. Это нормально и должно быть легко исправимо: обязательные поля, неверный формат, или правила вроде «скидка не может превышать 20%» или «сумма заказа должна быть > $0». UI должен выделять конкретное поле или правило, а не показывать общий алерт.
Ошибки auth обычно делятся на два случая: не аутентифицирован (не вошёл в систему, сессия истекла, отсутствует токен) и не авторизован (вошёл, но нет прав). Обрабатывайте их по-разному. «Пожалуйста, войдите снова» подходит для первого случая. Во втором — не раскрывайте чувствительных деталей, но будьте понятны: «У вас нет доступа для утверждения счетов».
Rate limiting означает «слишком много запросов, попробуйте позже». Часто появляется при импортах, загруженных дашбордах или повторных автоматических попытках. Указывайте hint с retry-after (даже просто «подождите 30 секунд»), и пусть UI делает backoff вместо того, чтобы бить сервер.
Сбои зависимостей происходят из-за внешних сервисов, таймаутов или просто аутейжа: провайдеры платежей, доставка SMS/почты, базы данных или внутренние сервисы. Пользователь не может это починить, так что UI должен предложить безопасный fallback (сохранить черновик, попробовать позже, связаться с поддержкой).
Главное отличие — поведение: ожидаемые ошибки являются частью нормального потока и требуют точной обратной связи; неожиданные ошибки сигнализируют о нестабильности и должны вызывать алерты, correlation ID и аккуратное логирование.
Таксономия должна быть достаточно маленькой, чтобы её можно было запомнить, но строгой настолько, чтобы две команды одинаково пометили ту же проблему.
Начните с 60–90-минутного воркшопа. Перечислите ошибки, которые встречаются чаще всего (плохой ввод, проблемы входа, слишком много запросов, сбои сторонних сервисов, неожиданные баги), затем сведите их к 6–12 категориям, которые команда сможет проговорить вслух, не заглядывая в доку.
Выберите шаблон именования, который остаётся читабельным в логах и тикетах. Держите коды короткими, избегайте номеров версий и считайте коды постоянными после релиза. Распространённый паттерн — префикс категории и понятный slug, например AUTH_INVALID_TOKEN или DEP_PAYMENT_TIMEOUT.
Перед окончанием встречи решите, что должно включать каждое сообщение об ошибке: category, code, безопасное сообщение, структурированные детали и trace/request ID.
Команды путаются, когда категории превращаются в мешок для всего. Простое правило помогает: категория отвечает «как UI и мониторинг должны реагировать», код отвечает «что именно произошло». Если два сбоя требуют разного поведения UI, они не должны быть в одной категории.
Решите, что пользователи видят по умолчанию. Validation подсвечивает поля. Auth отправляет на вход или показывает сообщение о доступе. Rate limits показывают «повторите через X секунд». Сбои зависимостей показывают спокойный экран с предложением повторить. Когда такие дефолты есть, новые фичи будут следовать им вместо придумывания индивидуальной обработки.
Прогоните пять общих потоков (signup, checkout, search, admin edit, file upload) и промаркируйте каждую ошибку. Если группа спорит — обычно нужен одно ясное правило, а не двадцать новых кодов.
Валидация — это тот тип ошибок, который обычно показывают сразу. Она должна быть предсказуемой: говорить пользователю, что исправить, и никогда не вызывать цикл повторных попыток.
Ошибки уровня поля и уровня формы — разные вещи. Ошибка поля относится к одному вводу (email, телефон, сумма). Ошибка формы — про сочетание полей (дата начала раньше даты окончания) или отсутствие предпосылки (не выбран способ доставки). Ответ API должен явно это показывать, чтобы UI мог корректно отреагировать.
Типичный бизнес-правило — «превышен кредитный лимит». Пользователь мог ввести валидное число, но действие запрещено для данного аккаунта. Рассматривайте это как ошибку уровня формы с понятной причиной и безопасной подсказкой, например: «Ваш доступный лимит $500. Уменьшите сумму или запросите увеличение.» Избегайте раскрытия внутренних имён полей, моделей скоринга или шагов правила.
Действительный ответ обычно включает стабильный код (не просто английское предложение), дружелюбное сообщение, опциональные указатели на поля для ошибок поля и небольшие безопасные подсказки (пример формата, допустимые диапазоны). Если нужен технический идентификатор правила для инженеров — кладите его в логи, а не в UI.
Логируйте ошибки валидации иначе, чем системные ошибки. Нужно достаточно контекста для поиска паттернов без хранения чувствительных данных. Логируйте user ID, request ID, имя правила или код и какие поля провалились. Для значений храните только необходимое (например, «присутствует/отсутствует» или длина) и маскируйте чувствительное.
В UI фокус на исправлении, а не на повторе. Подсвечивайте поля, сохраняйте введённое, прокручивайте к первой ошибке и отключайте автоматические повторы. Валидационные ошибки не временные, поэтому «попробуйте ещё раз» только тратит время.
Ошибки аутентификации и авторизации похожи для пользователя, но значат разное для безопасности, потоков UI и мониторинга. Их разделение делает поведение согласованным в вебе, мобильных клиентах и API.
Неаутентифицированность означает, что приложение не может доказать, кто пользователь. Типичные причины: отсутствуют креденшелы, токен недействителен или сессия истекла. Forbidden означает, что пользователь известен, но ему запрещено выполнять действие.
Просроченная сессия — самый частый кейс. Если вы поддерживаете refresh-токены, попробуйте бесшумный рефреш один раз, затем повторите исходный запрос. Если рефреш провалился, верните ошибку unauthenticated и отправьте пользователя на вход. Избегайте циклов: после одной попытки рефреша остановитесь и покажите ясный следующий шаг.
Поведение UI должно быть предсказуемым:
Для аудита логируйте достаточно, чтобы ответить на вопрос «кто что пытался сделать и почему это было заблокировано», не раскрывая секретов. Полезная запись включает user ID (если известен), тенант/рабочее пространство, имя действия, идентификатор ресурса, временную метку, request ID и результат проверки политики (allowed/denied). Держите сырые токены и пароли вне логов.
В сообщениях пользователю не раскрывайте имён ролей или структуры политики. «У вас нет доступа для утверждения счетов» безопаснее, чем «Только FinanceAdmin может утверждать счета.»
Rate limits — это не баги, а предохранитель. Обрабатывайте их как отдельную категорию, чтобы UI, логи и алерты одинаково реагировали, когда трафик скачет.
Лимиты проявляются в нескольких формах: на пользователя (один человек кликает слишком быстро), на IP (много пользователей за одним офисным IP) или на API-ключ (интеграция работает некорректно). Причина важна, потому что способ решения разный.
Клиентам нужны две вещи: что их ограничили и когда можно попробовать снова. Возвращайте HTTP 429 плюс ясное время ожидания (например, Retry-After: 30). Также добавляйте стабильный код ошибки (например, RATE_LIMITED), чтобы дашборды могли группировать события.
Держите сообщение спокойным и конкретным. «Too many requests» формально верно, но малоинформативно. «Подождите 30 секунд и попробуйте снова» задаёт ожидание и снижает повторные клики.
На стороне UI предотвращайте быстрые повторы. Простая схема: блокировать действие на период ожидания, показывать короткий обратный отсчёт и предлагать одну безопасную попытку по окончании таймера. Избегайте формулировок, которые заставят пользователей думать, что данные потеряны.
В мониторинге команды часто реагируют излишне остро. Не вызывайте дежурного при каждом 429. Следите за метриками и алертьте на аномальные всплески: резкий рост по конкретному endpoint, тенанту или API-ключу — это полезно.
На бэкенде поведение тоже должно быть предсказуемым. Используйте экспоненциальный backoff для автоматических повторов и делайте операции идемпотентными. Создание счета не должно создавать два счета, если первый запрос на самом деле прошёл.
Сбои зависимостей — это то, что пользователь не может исправить. Пользователь всё сделал правильно, но платежный шлюз не отвечает, соединение с БД упало или сторонний сервис вернул 5xx. Относите это в отдельную категорию, чтобы UI и мониторинг реагировали предсказуемо.
Начните с именования распространённых форм сбоев: таймаут, ошибка соединения (DNS, TLS, connection refused) и upstream 5xx (bad gateway, service unavailable). Даже если вы не знаете корень проблемы, вы можете зафиксировать, что произошло, и реагировать одинаково.
Повторы полезны при кратковременных сбоях, но они могут усугубить аварию. Используйте простые правила, чтобы все команды принимали одинаковые решения.
Когда зависимость падает, скажите пользователю, что он может сделать дальше, не обвиняя его: «Временная проблема. Попробуйте позже.» Если есть безопасный fallback, предложите его. Пример: если Stripe недоступен, позвольте сохранить заказ как «Ожидает оплаты» и отправьте подтверждение по почте вместо потери корзины.
Также защищайте от двойной отправки. Если пользователь нажал «Оплатить» дважды во время медленного ответа, система должна это обнаружить. Используйте idempotency-ключи для потоков «создать и списать» или проверки состояния вроде «заказ уже оплачен» перед повторным выполнением действия.
Для мониторинга логируйте поля, которые быстро отвечают на вопрос: «Какая зависимость падает и насколько серьёзно?» Захватывайте имя зависимости, endpoint или операцию, продолжительность и итог (timeout, connect, upstream 5xx). Это делает алерты и дашборды информативными, а не шумными.
Таксономии работают только когда все каналы говорят на одном языке: API, веб UI, мобильное приложение и логи. Иначе одна и та же проблема будет выглядеть как пять разных сообщений и никто не поймёт, пользовательская это ошибка или реальный аутейдж.
Относитесь к HTTP-статусам как к вторичному слою. Они помогают проксям и базовому поведению клиентов, но смысл несут category и code. Таймаут зависимости может быть 503, но категория подскажет UI предложить «Повторить» и скажет мониторингу пропейджить дежурного.
Сделайте так, чтобы каждый API возвращал единый стандартный формат ошибки, даже если источник разный (БД, auth-модуль, стороннее API). Простая форма держит обработку в UI и дашборды последовательными:
{
"category": "dependency",
"code": "PAYMENTS_TIMEOUT",
"message": "Payment service is not responding.",
"details": {"provider": "stripe"},
"correlation_id": "9f2c2c3a-6a2b-4a0a-9e9d-0b0c0c8b2b10"
}
Correlation ID — мост между «пользователь увидел ошибку» и «мы можем её проследить». Показывайте correlation_id в UI (кнопка копирования помогает) и всегда логируйте его на бэкенде, чтобы проследить запрос по сервисам.
Согласуйте, что безопасно показывать в UI, а что только в логах. Практичный разрыв: UI получает category, понятное сообщение и следующий шаг; логи получают технические детали ошибки и контекст запроса; общими для обоих остаются correlation_id и стабильный код ошибки.
Согласованность — скучная в лучшем смысле: каждый канал ведёт себя одинаково, а мониторинг говорит правду.
Проверьте бэкенд первым, включая background jobs и вебхуки. Если какое-то поле опционально, люди будут его пропускать и согласованность сломается.
Затем проверьте правила UI. Каждая категория должна соответствовать предсказуемому поведению экрана, чтобы пользователю не приходилось гадать: validation подсвечивает поля, auth предлагает вход или показывает сообщение об доступе, rate limits предлагают спокойное ожидание, dependency failures предлагают повтор и резервный вариант, когда это возможно.
Простой тест — вызвать по одной ошибке из каждой категории в стейджинге и проверить, что веб-приложение, мобильное приложение и админ-панель дают одинаковый результат.
Самый быстрый путь поломать систему ошибок — относиться к ней как к доделке на потом. Разные команды начинают использовать разные слова, коды и поведение UI для одной и той же проблемы. Работа над таксономией окупается, если её соблюдают.
Типичные ошибки:
Простой пример: менеджер отправляет форму «Создать клиента» и получает 403. Если UI считает все 4xx валидными ошибками, он подсветит случайные поля и предложит «исправить ввод», вместо того чтобы сказать, что требуется доступ. Мониторинг покажет всплеск «validation», хотя реальная проблема — роли.
Практичные следующие шаги, которые укладываются в один короткий воркшоп: написать одностраничный документ таксономии (категории, когда их применять, 5–10 канонических кодов), определить правила сообщений (что для пользователей, что для логов), ввести лёгкий процесс ревью для новых кодов, задать правила повторов по категориям, затем реализовать end-to-end (ответ бэкенда, маппинг в UI и дашборды мониторинга).
Если вы строите с AppMaster (appmaster.io), удобно централизовать эти правила в одном месте, чтобы поведение по категориям и кодам сохранялось в бэкенде, вебе и нативных мобильных приложениях.
Когда стоит заводить таксономию ошибок?Начните, когда один и тот же бэкенд обслуживает несколько клиентов (веб, мобильные приложения, внутренние инструменты) или когда служба поддержки и дежурные постоянно спрашивают: «Это ошибка пользователя или системная проблема?» Таксономия быстро окупается, когда у вас есть повторяющиеся сценарии — регистрация, оформление заказа, загрузки, правки админки — где важно единообразное поведение.
Сколько категорий ошибок стоит начать использовать?Хорошая отправная точка — 6–12 категорий, которые легко запомнить без просмотра документации. Держите категории широкими и стабильными (например, validation, auth, rate_limit, dependency, conflict, internal), а конкретику обозначайте кодом, а не новой категорией.
В чём разница между категорией ошибки и кодом ошибки?Категория задаёт поведение (что должно сделать UI и мониторинг), код — конкретно идентифицирует ситуацию. Категория отвечает «как реагировать», код — «что именно произошло». Код остаётся стабильным для дашбордов, алертов и скриптов поддержки даже если текст в UI поменяется.
Должно ли сообщение совпадать с кодом ошибки?Сообщения — это контент, а не идентификаторы. Возвращайте короткое, безопасное для пользователя сообщение в UI, а для группировки и автоматизации используйте стабильный код. Технические формулировки держите в логах и связывайте с тем же correlation ID при необходимости.
Что должно включать каждое ответное сообщение об ошибке в API?Включите категорию, стабильный код, безопасное сообщение для пользователя, структурированные детали и correlation/request ID. Детали должны быть такими, чтобы клиент мог на них опереться — например, какое поле не прошло проверку или сколько ждать — без вывода сырых текстов исключений.
Как сделать валидационные ошибки понятными и полезными для пользователей?Возвращайте указатели на поля, когда это возможно, чтобы UI мог подсветить конкретный ввод и сохранить то, что ввёл пользователь. Для ошибок уровня формы используйте отдельное поле, чтобы сообщить о проблеме сочетания полей или бизнес-правиле (например, ограничения по кредиту), а не пытаться угадать дефектное поле.
Как отличать ошибки «не вошёл в систему» и «нет прав»?«Неавторизован» (unauthenticated) означает, что пользователь не вошёл или токен просрочен — отправляйте на вход и сохраняйте задачу. «Запрещено» (forbidden) означает, что пользователь известен, но ему не хватает прав — оставайтесь на странице и покажите сообщение об отсутствии доступа, не раскрывая внутренних названий ролей или правил.
Как правильно реализовать ответы при превышении лимита запросов?Возвращайте явное время ожидания (например, значение Retry-After) и стабильный код, чтобы клиенты могли правильно делать backoff. В UI блокируйте повторные клики и показывайте понятный следующий шаг — автоматические многократные повторы обычно только ухудшают ситуацию.
Когда стоит повторять запросы к зависимостям и как избегать дублей?Повторяйте попытки только если ошибка скорее временная (таймауты, сброс соединения, upstream 502/503) и ограничивайте число попыток с небольшим backoff. Для неидемпотентных операций требуйте idempotency-ключ или проверки состояния, иначе повтор может создать дубликаты, если первый запрос всё же прошёл.
Как correlation ID помогают при инцидентах и где их показывать?Покажите correlation ID пользователю (чтобы поддержка могла его запросить) и всегда логируйте его на сервере вместе с кодом и ключевыми деталями. Это позволяет трассировать одну ошибку по сервисам; в проектах AppMaster (appmaster.io) удобно централизовать такую структуру, чтобы backend, веб и мобильные клиенты вели себя одинаково.
27 янв. 2026 г.
1 мин
26 янв. 2026 г.1 мин
21 янв. 2026 г.1 минЭкспериментируйте с AppMaster с бесплатной подпиской.
Как только вы будете готовы, вы сможете выбрать подходящий платный план.
