Backend Http Errors Openapi

3. Настроить маппинг бизнес-ошибок.

• Маппить исключения accessor/manager слоя в HTTP-ошибки на границе API (в handler).
• Ошибки валидации из __post_init__ в msgspec.Struct автоматически возвращают 400 через Litestar.
• Не пробрасывать внутренние исключения напрямую в клиентский контракт.

4. Задекларировать ошибки в OpenAPI.

• Для каждого endpoint явно перечислить ожидаемые error-responses.
• Для каждой ошибки отразить статус, схему envelope и доменный code.
• Использовать единый проектный способ описания responses (helper или ручной шаблон).
• Для versioned API поддерживать спецификацию ошибок в рамках api/v1/... и не переносить endpoint в новую версию без явного решения пользователя.

5. Сверить runtime и спецификацию.

• Проверить: каждая реально возможная ошибка есть в OpenAPI.
• Проверить: каждая ошибка из OpenAPI реально достижима в коде.

6. Проверить тестами.

• Добавить/обновить тесты на error-кейсы endpoint.
• Проверить ключевые статусы и ответ.
• uv run ruff check . + uv run pytest.

Anti-Patterns

• Документировать только success-ответы и скрывать error-контракт.
• Использовать нестабильные code (менять при каждом рефакторинге).
• Возвращать разные форматы ошибок в разных доменах.
• Описывать в OpenAPI ошибки, которые endpoint никогда не возвращает.

Definition Of Done

• Error-envelope единый по проекту.
• Доменные HTTP-ошибки вынесены и именованы консистентно.
• OpenAPI покрывает все ожидаемые ошибки endpoint-ов.
• Тесты подтверждают соответствие runtime-ошибок и OpenAPI-контракта.