Единый подход к ошибкам в backend: доменные ошибки, маппинг в gRPC/HTTP и логирование.

Доменные ошибки (core)

В core/<aggregate>/errors.py или core/errors.py определяются исключения:

1
2
3
4
5

class DomainError(Exception): ...

class UserAlreadyExistsError(DomainError): ...
class UserNotFoundError(DomainError): ...
class InvalidUsernameError(DomainError): ...

Они не содержат stack trace в сообщении для клиента; детали только в логах.

Use case

Use case вызывает domain logic и репозитории; при нарушении бизнес-правил выбрасывает доменную ошибку. Не перехватывает технические исключения БД/Kafka — они пробрасываются выше для централизованной обработки.

API layer (gRPC)

• Перехват исключений в interceptor или в servicer.
• Маппинг:
• UserAlreadyExistsError → grpc.StatusCode.ALREADY_EXISTS
• UserNotFoundError → grpc.StatusCode.NOT_FOUND
• InvalidUsernameError → grpc.StatusCode.INVALID_ARGUMENT
• Неизвестные Exception → grpc.StatusCode.INTERNAL, сообщение общее («Internal error»), полное исключение только в логах.

Логирование

• Все ошибки логируются с уровнем и контекстом (request_id, user_id).
• Без паролей, токенов и PII в логах (используется PII sanitizer при необходимости).
• Stack trace — только для неожиданных исключений (INTERNAL).

Retry и resilience

• Для вызовов внешних сервисов и Kafka — ограниченные retry с backoff (настраивается в клиентах).
• Для БД — транзакция откатывается при ошибке; клиент может повторить запрос при идемпотентном API.

Связанные страницы

• API Guidelines — коды gRPC и HTTP
• Backend Overview
• Reliability / Fault Tolerance