Какие недостатки у выбрасывания стандартных RuntimeError в API-эндпоинтах?

Question

RuntimeError не несёт бизнес-смысла и плохо подходит для API. Клиент получает неинформативный ответ и часто статус 500, даже если ошибка ожидаемая. Такие ошибки сложно логировать и анализировать. В результате API становится непредсказуемым для пользователей.

YeaHub · Accepted Answer

ОпределениеRuntimeError — это общее исключение, сигнализирующее о проблеме выполнения без уточнения причины и контекста.Почему это проблема в APIAPI — это контракт, и ошибки в нём должны быть частью этого контракта.Отсутствие семантикинеясно, ошибка клиента или сервераневозможно понять, что именно пошло не такНеправильные HTTP-статусыбизнес-ошибка превращается в 500клиент не понимает, можно ли повторять запросПлохая диагностикаошибки сложно классифицироватьлоги теряют смысл без контекстаНарушение контракта APIформат ошибок нестабиленфронтенд вынужден обрабатывать «всё подряд»Типовой антипримерif balance < amount:
    raise RuntimeError("Not enough money")
Как лучшеиспользовать доменные исключениямаппить их на HTTP-статусывозвращать структурированные ошибкиВыводВ API ошибки должны быть осмысленными, предсказуемыми и частью публичного контракта, а не побочным эффектом выполнения кода.