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

Определение

RuntimeError — это общее исключение, сигнализирующее о проблеме выполнения без уточнения причины и контекста.

Почему это проблема в API

API — это контракт, и ошибки в нём должны быть частью этого контракта.

1. Отсутствие семантики

   • неясно, ошибка клиента или сервера

   • невозможно понять, что именно пошло не так

2. Неправильные HTTP-статусы

   • бизнес-ошибка превращается в 500

   • клиент не понимает, можно ли повторять запрос

3. Плохая диагностика

   • ошибки сложно классифицировать

   • логи теряют смысл без контекста

4. Нарушение контракта API

   • формат ошибок нестабилен

   • фронтенд вынужден обрабатывать «всё подряд»

Типовой антипример

if balance < amount:
    raise RuntimeError("Not enough money")

Как лучше

• использовать доменные исключения

• маппить их на HTTP-статусы

• возвращать структурированные ошибки

Вывод

В API ошибки должны быть осмысленными, предсказуемыми и частью публичного контракта, а не побочным эффектом выполнения кода.