voidea/docs/error-handling.md

Обработка ошибок

Иерархия исключений

# app/core/exceptions.py
AppError
├── AuthenticationError    # 401 — неверный токен/пароль
├── ForbiddenError         # 403 — нет прав
├── NotFoundError          # 404 — ресурс не найден
├── ConflictError          # 409 — дубликат, конфликт
├── ValidationError        # 422 — неверные данные
└── ServiceUnavailableError # 503 — внешний сервис недоступен

Матрица по слоям

Слой	Что делаем	Пример
API	HTTPException с detail и status_code	raise HTTPException(404)
Services	Бизнес-исключения (из AppError)	raise NotFoundError("Idea", id)
Integrations	try/except с fallback	return AIResult(success=False)
Agents	AgentResult(success=False, error=...)	Без HTTP-статусов
Data/DB	Ошибки не всплывают выше	Ловим в сервисе

Fallback pattern (AI провайдеры)

# app/integrations/ai/fallback.py
# YandexGPT → GigaChat, 2 retry, 2s/5s backoff
# При недоступности всех — AgentResult(success=False, message=...)

Graceful degradation

Сервис недоступен	Реакция
PostgreSQL	503 Service Unavailable
Redis	Работаем без Celery (прямой вызов), log WARNING
AI провайдер	Fallback на другой, потом Error
Celery	Выполняем задачу синхронно

Логирование ошибок

Уровень	Когда
WARNING	Timeout, retry, fallback
ERROR	Ошибка внешнего API
CRITICAL	Исчерпаны все retry