Как обрабатывать исключения в FastAPI

В FastAPI я использую HTTPException и собственные классы ошибок, а обработку исключений выношу в общие хендлеры через app.exception_handler или add_exception_handler, чтобы формировать единообразные JSON‑ответы.

Так контроллеры остаются простыми, а всё логирование и маппинг ошибок на status_code и человекочитаемые сообщения выполняется централизованно.

Базовый способ обработки ошибок в FastAPI — выбрасывать HTTPException с нужными полями status_code и detail. Так клиент получает корректный HTTP‑код и описательное сообщение об ошибке.

Например, если при обращении к /items/0 объект не найден, можно вернуть ошибку 404:

Однако кидать «сырые» HTTPException прямо из каждого контроллера считается плохим тоном: логика обработки ошибок расползается по коду, её сложно переиспользовать и централизованно менять. Лучше, чтобы бизнес‑код и эндпоинты выбрасывали свои доменные исключения, а уже отдельные хендлеры переводили их в HTTP‑ответы.

• Внутри сервисов и репозиториев выбрасывайте собственные исключения (например, ItemNotFoundError).
• Регистрируйте глобальные обработчики через @app.exception_handler или app.add_exception_handler, где настраиваете HTTP‑код, структуру JSON‑ответа и логирование.
• Так одинаковые исключения, выбрасываемые из разных эндпоинтов, обрабатываются единообразно, а контроллеры остаются максимально «тонкими».

Пример: создаём своё исключение и единый хендлер, который конвертирует его в структурированный JSON‑ответ с нужным статусом: