feat(errors): implement RFC 7807 compliant domain exception handling

Author: PyDevDeep

backend/api/main.py

@@ -1,10 +1,14 @@
 import structlog
 from fastapi import FastAPI
 
-from backend.api.middleware.error_handler import global_exception_handler
+from backend.api.middleware.error_handler import (
+    domain_exception_handler,
+    global_exception_handler,
+)
 from backend.api.middleware.logging import StructuredLoggingMiddleware
 from backend.api.routes import drafts, feedback, health
 from backend.config.settings import settings
+from backend.services.exceptions import DomainError
 
 # Basic structlog configuration for JSON output
 structlog.configure(
@@ -28,6 +32,7 @@ def create_app() -> FastAPI:
     )
 
     app.add_middleware(StructuredLoggingMiddleware)
+    app.add_exception_handler(DomainError, domain_exception_handler)
     app.add_exception_handler(Exception, global_exception_handler)
     app.include_router(health.router, prefix="/api/v1")
     app.include_router(drafts.router, prefix="/api/v1")

backend/api/middleware/error_handler.py

@@ -2,19 +2,91 @@
 from fastapi import Request, status
 from fastapi.responses import JSONResponse
 
+from backend.services.exceptions import (
+    DraftNotFoundError,
+    PublishingFailedError,
+    UnsupportedPlatformError,
+)
+
 logger = structlog.get_logger()
 
+_PROBLEM_TYPE_BASE = "https://serotonin-script.internal/errors"
+
+
+def _problem(
+    request: Request,
+    status_code: int,
+    title: str,
+    detail: str,
+    extra: dict[str, object] | None = None,
+) -> JSONResponse:
+    """Return an RFC 7807 Problem Details response."""
+    body: dict[str, object] = {
+        "type": f"{_PROBLEM_TYPE_BASE}/{title.lower().replace(' ', '-')}",
+        "title": title,
+        "status": status_code,
+        "detail": detail,
+        "instance": request.url.path,
+    }
+    if extra:
+        body.update(extra)
+    return JSONResponse(status_code=status_code, content=body)
+
+
+async def domain_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Map domain errors to structured RFC 7807 HTTP responses."""
+    if isinstance(exc, DraftNotFoundError):
+        return _problem(
+            request,
+            status.HTTP_404_NOT_FOUND,
+            "Draft Not Found",
+            str(exc),
+            {"draft_id": str(exc.draft_id)},
+        )
+    if isinstance(exc, UnsupportedPlatformError):
+        return _problem(
+            request,
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            "Unsupported Platform",
+            str(exc),
+            {"platform": exc.platform},
+        )
+    if isinstance(exc, PublishingFailedError):
+        logger.error(
+            "publishing_failed",
+            platform=str(exc.platform),
+            reason=exc.reason,
+            path=request.url.path,
+        )
+        return _problem(
+            request,
+            status.HTTP_502_BAD_GATEWAY,
+            "Publishing Failed",
+            str(exc),
+            {"platform": str(exc.platform)},
+        )
+    # Catch-all for any future DomainError subclasses
+    logger.error("unhandled_domain_error", error=str(exc), path=request.url.path)
+    return _problem(
+        request,
+        status.HTTP_400_BAD_REQUEST,
+        "Domain Error",
+        str(exc),
+    )
+
 
 async def global_exception_handler(request: Request, exc: Exception) -> JSONResponse:
-    """Handle all unhandled exceptions and return a 500 JSON response."""
+    """Handle all unhandled exceptions and return a 500 RFC 7807 response."""
     logger.error(
         "unhandled_exception",
         error=str(exc),
         error_type=type(exc).__name__,
         path=request.url.path,
         method=request.method,
     )
-    return JSONResponse(
-        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-        content={"detail": "Internal server error occurred."},
+    return _problem(
+        request,
+        status.HTTP_500_INTERNAL_SERVER_ERROR,
+        "Internal Server Error",
+        "An unexpected error occurred.",
     )

backend/services/exceptions.py

@@ -0,0 +1,30 @@
+from backend.models.enums import Platform
+
+
+class DomainError(Exception):
+    """Base class for all domain-level errors."""
+
+
+class DraftNotFoundError(DomainError):
+    """Raised when a requested draft does not exist."""
+
+    def __init__(self, draft_id: int | str) -> None:
+        super().__init__(f"Draft '{draft_id}' not found.")
+        self.draft_id = draft_id
+
+
+class PublishingFailedError(DomainError):
+    """Raised when publishing to a social platform fails."""
+
+    def __init__(self, platform: Platform | str, reason: str) -> None:
+        super().__init__(f"Publishing to '{platform}' failed: {reason}")
+        self.platform = platform
+        self.reason = reason
+
+
+class UnsupportedPlatformError(DomainError):
+    """Raised when no publisher is registered for the requested platform."""
+
+    def __init__(self, platform: str) -> None:
+        super().__init__(f"No publisher registered for platform '{platform}'.")
+        self.platform = platform