social-app/.trellis/spec/backend/error-handling.md

Error Handling

How errors are handled in this project.

---

Overview

Backend error transport is RFC7807-style application/problem+json with stable code and optional params extensions.

Evidence:

• Error class: backend/src/core/http/errors.py (ApiProblemError)
• Problem details builder: backend/src/core/http/response.py
• Global exception mapping: backend/src/app.py
• Error code registry: docs/protocols/common/http-error-codes.md

---

Error Types

1) ApiProblemError (preferred for business/API errors)

Used to carry status_code, detail, code, params.

Examples:

• backend/src/v1/todo/service.py (_todo_error(...) returns ApiProblemError)
• backend/src/v1/schedule_items/service.py (raises ApiProblemError with problem_payload(...))
• backend/src/v1/users/dependencies.py (auth failures mapped to AUTH_UNAUTHORIZED, JWT_VERIFIER_NOT_CONFIGURED)

2) Infra/DB exceptions (caught at boundary and converted)

• SQLAlchemyError is commonly caught in service/repository boundaries.
• Many repository methods log and re-raise DB exceptions (for example in todo/schedule_items repositories); generic helpers in core/db/base_repository.py may just propagate exceptions.
• Service layer usually maps infra failures to stable codes like *_SERVICE_UNAVAILABLE / *_STORE_UNAVAILABLE.

Examples:

• backend/src/v1/todo/repository.py
• backend/src/v1/todo/service.py
• backend/src/v1/schedule_items/service.py

---

Error Handling Patterns

Observed patterns:

1. Service methods: catch DB/infrastructure errors, rollback when needed, then raise typed API problem.
   • backend/src/v1/todo/service.py
   • backend/src/v1/schedule_items/service.py
2. Repository methods: log exception context and re-raise.
   • backend/src/v1/todo/repository.py
   • backend/src/v1/schedule_items/repository.py
3. Global handlers: convert unhandled errors and framework exceptions into problem+json responses.
   • backend/src/app.py

---

API Error Responses

Expected transport:

• Media type: application/problem+json
• Fields: RFC7807 core (type, title, status, detail, instance) + extension fields (code, params)

Evidence:

• Response builder model in backend/src/core/http/response.py
• Exception handlers in backend/src/app.py
• Registry and compatibility notes in docs/protocols/common/http-error-codes.md

Practical rule:

• For business branches, return stable UPPER_SNAKE_CASE codes and keep detail human-readable.

---

Anti-patterns / Forbidden Patterns

• Do not return free-text-only errors for business branches (missing code).
  • Protocol source: docs/protocols/common/http-error-codes.md
• Do not swallow exceptions with except ...: log; return default in new code.
  • Project-wide rule from root AGENTS.md: no error swallowing.
• Do not add new service/repository branches that raise HTTPException directly.
  • Backend target rule in backend/AGENTS.md prefers ApiProblemError in non-router layers.

Existing legacy evidence to be aware of:

• backend/src/core/db/base_service.py still raises HTTPException(401, "Unauthorized").
• backend/src/v1/users/dependencies.py has fallback branches returning None after catching exceptions in _verify_user_with_supabase.

These are current-state observations, not patterns to copy for new code.

---

Uncertainties (documented, not invented)

• backend/src/core/logging/middleware.py defines register_exception_handlers(...) returning { "detail": "Internal Server Error" } JSON (non-problem+json); main app currently defines its own handlers in backend/src/app.py. The single enforced runtime path should be clarified before broad refactors.
• There is no automated CI check in this repo yet that verifies every endpoint always includes code in all error branches; compliance is currently convention + review driven.