response structure

app.py

@@ -4,11 +4,13 @@ FastAPI Application - API Gateway with credit management and AI services.
 import os
 import logging
 from contextlib import asynccontextmanager
-from fastapi import FastAPI, Request
+from fastapi import FastAPI, Request, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
 
 from core.database import engine, DB_FILENAME
+from core.api_response import APIError, error_response, status_to_error_code, ErrorCode
 from routers import auth, blink, contact, credits, general, gemini, payments, schema
 from services.drive_service import DriveService
 from services.db_service import init_database, reset_database
@@ -258,13 +260,57 @@ app.include_router(contact.router)
 app.include_router(schema.router)
 
 
+@app.exception_handler(APIError)
+async def api_error_handler(request: Request, exc: APIError):
+    """Handle custom APIError exceptions with standardized format."""
+    logger.warning(f"API Error: {exc.code} - {exc.message}")
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response(exc.code, exc.message, exc.details)
+    )
+
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException):
+    """Convert HTTPException to standardized error format."""
+    code = status_to_error_code(exc.status_code)
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response(code, str(exc.detail))
+    )
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Handle Pydantic validation errors with detailed field info."""
+    errors = []
+    for error in exc.errors():
+        errors.append({
+            "field": ".".join(str(loc) for loc in error["loc"]),
+            "message": error["msg"],
+            "type": error["type"]
+        })
+    
+    return JSONResponse(
+        status_code=422,
+        content=error_response(
+            ErrorCode.VALIDATION_ERROR,
+            "Request validation failed",
+            {"errors": errors}
+        )
+    )
+
+
 @app.exception_handler(Exception)
 async def global_exception_handler(request: Request, exc: Exception):
-    """Global exception handler."""
-    logger.error(f"Unhandled exception: {exc}")
+    """Global exception handler for unexpected errors."""
+    logger.error(f"Unhandled exception: {exc}", exc_info=True)
     return JSONResponse(
         status_code=500,
-        content={"detail": "Internal server error"}
+        content=error_response(
+            ErrorCode.SERVER_ERROR,
+            "An unexpected error occurred. Please try again later."
+        )
     )
 
 

core/api_response.py

@@ -0,0 +1,268 @@
+"""
+API Response - Standardized API response structure.
+
+Provides consistent success/error response formats for all API endpoints.
+Clients can use a unified handler for both success and error responses.
+
+Success Response:
+{
+    "success": true,
+    "message": "Operation completed successfully",
+    "data": { ... }
+}
+
+Error Response:
+{
+    "success": false,
+    "error": {
+        "code": "INSUFFICIENT_CREDITS",
+        "message": "You don't have enough credits",
+        "details": { ... }
+    }
+}
+
+Usage:
+    # In routers - raising errors
+    from core.api_response import APIError, ErrorCode
+    
+    raise APIError(
+        code=ErrorCode.INSUFFICIENT_CREDITS,
+        message="You need at least 10 credits",
+        status_code=402,
+        details={"required": 10, "available": 5}
+    )
+    
+    # In routers - success response
+    from core.api_response import success_response
+    
+    return success_response(
+        data={"job_id": "123", "status": "queued"},
+        message="Job created successfully"
+    )
+"""
+
+from typing import Optional, Any, Dict
+from pydantic import BaseModel, Field
+
+
+# =============================================================================
+# Error Codes - Machine-readable error identifiers
+# =============================================================================
+
+class ErrorCode:
+    """Standard error codes for consistent client handling."""
+    
+    # Authentication errors (401)
+    UNAUTHORIZED = "UNAUTHORIZED"
+    TOKEN_EXPIRED = "TOKEN_EXPIRED"
+    TOKEN_INVALID = "TOKEN_INVALID"
+    
+    # Authorization errors (403)
+    FORBIDDEN = "FORBIDDEN"
+    ADMIN_REQUIRED = "ADMIN_REQUIRED"
+    
+    # Payment/Credits errors (402)
+    INSUFFICIENT_CREDITS = "INSUFFICIENT_CREDITS"
+    PAYMENT_REQUIRED = "PAYMENT_REQUIRED"
+    PAYMENT_FAILED = "PAYMENT_FAILED"
+    
+    # Resource errors (404)
+    NOT_FOUND = "NOT_FOUND"
+    USER_NOT_FOUND = "USER_NOT_FOUND"
+    JOB_NOT_FOUND = "JOB_NOT_FOUND"
+    
+    # Validation errors (400, 422)
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    BAD_REQUEST = "BAD_REQUEST"
+    INVALID_INPUT = "INVALID_INPUT"
+    
+    # Rate limiting (429)
+    RATE_LIMITED = "RATE_LIMITED"
+    TOO_MANY_REQUESTS = "TOO_MANY_REQUESTS"
+    
+    # Service errors (5xx)
+    SERVER_ERROR = "SERVER_ERROR"
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR"
+    
+    # Business logic errors
+    JOB_ALREADY_PROCESSING = "JOB_ALREADY_PROCESSING"
+    JOB_EXPIRED = "JOB_EXPIRED"
+    OPERATION_NOT_ALLOWED = "OPERATION_NOT_ALLOWED"
+
+
+# =============================================================================
+# Pydantic Models - For OpenAPI documentation
+# =============================================================================
+
+class ErrorDetail(BaseModel):
+    """Structured error information."""
+    code: str = Field(..., description="Machine-readable error code")
+    message: str = Field(..., description="Human-readable error message")
+    details: Optional[Dict[str, Any]] = Field(
+        None, 
+        description="Additional context about the error"
+    )
+
+
+class ApiErrorResponse(BaseModel):
+    """Standard error response format."""
+    success: bool = Field(False, description="Always false for errors")
+    error: ErrorDetail = Field(..., description="Error details")
+
+
+class ApiSuccessResponse(BaseModel):
+    """Standard success response format."""
+    success: bool = Field(True, description="Always true for success")
+    message: Optional[str] = Field(None, description="Optional success message")
+    data: Optional[Dict[str, Any]] = Field(None, description="Response payload")
+
+
+# =============================================================================
+# Custom Exception - For raising API errors
+# =============================================================================
+
+class APIError(Exception):
+    """
+    Custom exception for API errors with structured response.
+    
+    Raise this exception anywhere in your code, and the global exception
+    handler will convert it to a standardized JSON response.
+    
+    Example:
+        raise APIError(
+            code=ErrorCode.INSUFFICIENT_CREDITS,
+            message="You need at least 10 credits for this operation",
+            status_code=402,
+            details={"required": 10, "available": 5}
+        )
+    """
+    
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status_code: int = 400,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.details = details
+        super().__init__(message)
+    
+    def to_dict(self) -> dict:
+        """Convert to response dictionary."""
+        return error_response(self.code, self.message, self.details)
+
+
+# =============================================================================
+# Helper Functions - For building responses
+# =============================================================================
+
+def success_response(
+    data: Optional[Dict[str, Any]] = None,
+    message: Optional[str] = None
+) -> dict:
+    """
+    Create a standardized success response.
+    
+    Args:
+        data: Response payload (dict)
+        message: Optional success message
+        
+    Returns:
+        dict: {"success": true, "message": "...", "data": {...}}
+        
+    Example:
+        return success_response(
+            data={"job_id": "123", "status": "queued"},
+            message="Job created successfully"
+        )
+    """
+    response = {"success": True}
+    if message:
+        response["message"] = message
+    if data is not None:
+        response["data"] = data
+    return response
+
+
+def error_response(
+    code: str,
+    message: str,
+    details: Optional[Dict[str, Any]] = None
+) -> dict:
+    """
+    Create a standardized error response.
+    
+    Args:
+        code: Machine-readable error code (use ErrorCode constants)
+        message: Human-readable error message
+        details: Optional additional context
+        
+    Returns:
+        dict: {"success": false, "error": {"code": "...", "message": "...", "details": {...}}}
+        
+    Example:
+        return error_response(
+            code=ErrorCode.NOT_FOUND,
+            message="Job not found",
+            details={"job_id": "xyz"}
+        )
+    """
+    error = {
+        "code": code,
+        "message": message
+    }
+    if details is not None:
+        error["details"] = details
+    
+    return {
+        "success": False,
+        "error": error
+    }
+
+
+def status_to_error_code(status_code: int) -> str:
+    """
+    Map HTTP status code to a default error code.
+    
+    Args:
+        status_code: HTTP status code
+        
+    Returns:
+        str: Corresponding error code
+    """
+    mapping = {
+        400: ErrorCode.BAD_REQUEST,
+        401: ErrorCode.UNAUTHORIZED,
+        402: ErrorCode.PAYMENT_REQUIRED,
+        403: ErrorCode.FORBIDDEN,
+        404: ErrorCode.NOT_FOUND,
+        422: ErrorCode.VALIDATION_ERROR,
+        429: ErrorCode.RATE_LIMITED,
+        500: ErrorCode.SERVER_ERROR,
+        502: ErrorCode.EXTERNAL_SERVICE_ERROR,
+        503: ErrorCode.SERVICE_UNAVAILABLE,
+    }
+    return mapping.get(status_code, ErrorCode.SERVER_ERROR)
+
+
+__all__ = [
+    # Error codes
+    'ErrorCode',
+    
+    # Pydantic models
+    'ErrorDetail',
+    'ApiErrorResponse',
+    'ApiSuccessResponse',
+    
+    # Exception
+    'APIError',
+    
+    # Helper functions
+    'success_response',
+    'error_response',
+    'status_to_error_code',
+]

services/auth_service/middleware.py

@@ -14,6 +14,7 @@ from starlette.middleware.base import BaseHTTPMiddleware
 
 from core.database import async_session_maker
 from core.models import User
+from core.api_response import error_response, ErrorCode
 from services.auth_service.config import AuthServiceConfig
 from services.auth_service.jwt_provider import (
     verify_access_token,
@@ -91,7 +92,10 @@ class AuthMiddleware(BaseServiceMiddleware):
                 self.log_request(request, "Missing Authorization header (required)")
                 return JSONResponse(
                     status_code=status.HTTP_401_UNAUTHORIZED,
-                    content={"detail": "Missing Authorization header"},
+                    content=error_response(
+                        ErrorCode.UNAUTHORIZED,
+                        "Missing Authorization header"
+                    ),
                     headers={"WWW-Authenticate": "Bearer"},
                 )
             else:
@@ -109,7 +113,10 @@ class AuthMiddleware(BaseServiceMiddleware):
                 self.log_request(request, "Invalid Authorization header format")
                 return JSONResponse(
                     status_code=status.HTTP_401_UNAUTHORIZED,
-                    content={"detail": "Invalid Authorization header format. Use: Bearer <token>"},
+                    content=error_response(
+                        ErrorCode.TOKEN_INVALID,
+                        "Invalid Authorization header format. Use: Bearer <token>"
+                    ),
                     headers={"WWW-Authenticate": "Bearer"},
                 )
             else:
@@ -131,7 +138,10 @@ class AuthMiddleware(BaseServiceMiddleware):
                 self.log_request(request, "Token expired")
                 return JSONResponse(
                     status_code=status.HTTP_401_UNAUTHORIZED,
-                    content={"detail": "Token has expired. Please sign in again."},
+                    content=error_response(
+                        ErrorCode.TOKEN_EXPIRED,
+                        "Token has expired. Please sign in again."
+                    ),
                     headers={"WWW-Authenticate": "Bearer"},
                 )
             else:
@@ -146,7 +156,10 @@ class AuthMiddleware(BaseServiceMiddleware):
                 self.log_error(request, f"Token verification failed: {e}")
                 return JSONResponse(
                     status_code=status.HTTP_401_UNAUTHORIZED,
-                    content={"detail": f"Invalid token: {str(e)}"},
+                    content=error_response(
+                        ErrorCode.TOKEN_INVALID,
+                        f"Invalid token: {str(e)}"
+                    ),
                     headers={"WWW-Authenticate": "Bearer"},
                 )
             else:
@@ -173,7 +186,10 @@ class AuthMiddleware(BaseServiceMiddleware):
                         self.log_request(request, "User not found or inactive")
                         return JSONResponse(
                             status_code=status.HTTP_401_UNAUTHORIZED,
-                            content={"detail": "User not found or inactive"},
+                            content=error_response(
+                                ErrorCode.USER_NOT_FOUND,
+                                "User not found or inactive"
+                            ),
                         )
                     else:
                         # Optional auth, user not found
@@ -183,7 +199,6 @@ class AuthMiddleware(BaseServiceMiddleware):
                         response = await call_next(request)
                         return response
                 
-                # Validate token version
                 if payload.token_version < user.token_version:
                     if requires_auth:
                         self.log_request(
@@ -192,7 +207,10 @@ class AuthMiddleware(BaseServiceMiddleware):
                         )
                         return JSONResponse(
                             status_code=status.HTTP_401_UNAUTHORIZED,
-                            content={"detail": "Token has been invalidated. Please sign in again."},
+                            content=error_response(
+                                ErrorCode.TOKEN_INVALID,
+                                "Token has been invalidated. Please sign in again."
+                            ),
                             headers={"WWW-Authenticate": "Bearer"},
                         )
                     else:

services/credit_service/middleware.py

@@ -11,6 +11,7 @@ from fastapi.responses import JSONResponse, Response
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from core.database import async_session_maker
+from core.api_response import error_response, ErrorCode
 from services.credit_service.config import CreditServiceConfig
 from services.credit_service.transaction_manager import (
     CreditTransactionManager,
@@ -58,7 +59,10 @@ class CreditMiddleware(BaseServiceMiddleware):
         if not user:
             return JSONResponse(
                 status_code=status.HTTP_401_UNAUTHORIZED,
-                content={"detail": "Authentication required for this endpoint"}
+                content=error_response(
+                    ErrorCode.UNAUTHORIZED,
+                    "Authentication required for this endpoint"
+                )
             )
         
         # Reserve credits
@@ -95,18 +99,24 @@ class CreditMiddleware(BaseServiceMiddleware):
                 await db.rollback()
                 return JSONResponse(
                     status_code=status.HTTP_402_PAYMENT_REQUIRED,
-                    content={
-                        "detail": f"Insufficient credits. Required: {credit_cost}, Available: {user.credits}",
-                        "credits_required": credit_cost,
-                        "credits_available": user.credits
-                    }
+                    content=error_response(
+                        ErrorCode.INSUFFICIENT_CREDITS,
+                        f"Insufficient credits. Required: {credit_cost}, Available: {user.credits}",
+                        {
+                            "credits_required": credit_cost,
+                            "credits_available": user.credits
+                        }
+                    )
                 )
             except Exception as e:
                 await db.rollback()
                 logger.error(f"Credit reservation failed: {e}", exc_info=True)
                 return JSONResponse(
                     status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                    content={"detail": "Failed to reserve credits"}
+                    content=error_response(
+                        ErrorCode.SERVER_ERROR,
+                        "Failed to reserve credits"
+                    )
                 )
         
 

tests/test_api_response.py

@@ -0,0 +1,271 @@
+"""
+Tests for API Response module.
+
+Tests the standardized API response format, exception handlers, 
+and helper functions.
+"""
+
+import pytest
+from fastapi import FastAPI, HTTPException
+from fastapi.testclient import TestClient
+from fastapi.exceptions import RequestValidationError
+from pydantic import BaseModel, Field
+
+from core.api_response import (
+    ErrorCode,
+    ErrorDetail,
+    ApiErrorResponse,
+    ApiSuccessResponse,
+    APIError,
+    success_response,
+    error_response,
+    status_to_error_code,
+)
+
+
+# =============================================================================
+# Unit Tests - Helper Functions
+# =============================================================================
+
+class TestSuccessResponse:
+    """Test success_response helper function."""
+    
+    def test_basic_success(self):
+        """success_response returns correct format."""
+        result = success_response()
+        assert result == {"success": True}
+    
+    def test_success_with_data(self):
+        """success_response includes data when provided."""
+        data = {"job_id": "123", "status": "queued"}
+        result = success_response(data=data)
+        
+        assert result["success"] is True
+        assert result["data"] == data
+        assert "message" not in result
+    
+    def test_success_with_message(self):
+        """success_response includes message when provided."""
+        result = success_response(message="Job created")
+        
+        assert result["success"] is True
+        assert result["message"] == "Job created"
+        assert "data" not in result
+    
+    def test_success_with_data_and_message(self):
+        """success_response includes both data and message."""
+        data = {"id": 1}
+        result = success_response(data=data, message="Success!")
+        
+        assert result["success"] is True
+        assert result["data"] == data
+        assert result["message"] == "Success!"
+
+
+class TestErrorResponse:
+    """Test error_response helper function."""
+    
+    def test_basic_error(self):
+        """error_response returns correct format."""
+        result = error_response(
+            code=ErrorCode.NOT_FOUND,
+            message="Job not found"
+        )
+        
+        assert result["success"] is False
+        assert result["error"]["code"] == "NOT_FOUND"
+        assert result["error"]["message"] == "Job not found"
+        assert "details" not in result["error"]
+    
+    def test_error_with_details(self):
+        """error_response includes details when provided."""
+        result = error_response(
+            code=ErrorCode.INSUFFICIENT_CREDITS,
+            message="Not enough credits",
+            details={"required": 10, "available": 5}
+        )
+        
+        assert result["success"] is False
+        assert result["error"]["code"] == "INSUFFICIENT_CREDITS"
+        assert result["error"]["details"]["required"] == 10
+        assert result["error"]["details"]["available"] == 5
+
+
+class TestStatusToErrorCode:
+    """Test status_to_error_code mapping function."""
+    
+    def test_401_maps_to_unauthorized(self):
+        assert status_to_error_code(401) == ErrorCode.UNAUTHORIZED
+    
+    def test_402_maps_to_payment_required(self):
+        assert status_to_error_code(402) == ErrorCode.PAYMENT_REQUIRED
+    
+    def test_404_maps_to_not_found(self):
+        assert status_to_error_code(404) == ErrorCode.NOT_FOUND
+    
+    def test_429_maps_to_rate_limited(self):
+        assert status_to_error_code(429) == ErrorCode.RATE_LIMITED
+    
+    def test_500_maps_to_server_error(self):
+        assert status_to_error_code(500) == ErrorCode.SERVER_ERROR
+    
+    def test_unknown_maps_to_server_error(self):
+        """Unknown status codes default to SERVER_ERROR."""
+        assert status_to_error_code(418) == ErrorCode.SERVER_ERROR
+
+
+# =============================================================================
+# Unit Tests - APIError Exception
+# =============================================================================
+
+class TestAPIError:
+    """Test APIError custom exception."""
+    
+    def test_api_error_attributes(self):
+        """APIError stores all attributes correctly."""
+        error = APIError(
+            code=ErrorCode.INSUFFICIENT_CREDITS,
+            message="Need more credits",
+            status_code=402,
+            details={"needed": 10}
+        )
+        
+        assert error.code == ErrorCode.INSUFFICIENT_CREDITS
+        assert error.message == "Need more credits"
+        assert error.status_code == 402
+        assert error.details == {"needed": 10}
+    
+    def test_api_error_default_status(self):
+        """APIError defaults to 400 status code."""
+        error = APIError(
+            code=ErrorCode.BAD_REQUEST,
+            message="Invalid input"
+        )
+        
+        assert error.status_code == 400
+        assert error.details is None
+    
+    def test_api_error_to_dict(self):
+        """APIError.to_dict() returns correct format."""
+        error = APIError(
+            code=ErrorCode.NOT_FOUND,
+            message="Resource not found",
+            details={"id": "xyz"}
+        )
+        
+        result = error.to_dict()
+        assert result["success"] is False
+        assert result["error"]["code"] == "NOT_FOUND"
+        assert result["error"]["message"] == "Resource not found"
+        assert result["error"]["details"]["id"] == "xyz"
+    
+    def test_api_error_is_exception(self):
+        """APIError can be raised and caught as Exception."""
+        with pytest.raises(APIError) as exc_info:
+            raise APIError(code="TEST", message="Test error")
+        
+        assert exc_info.value.code == "TEST"
+        assert str(exc_info.value) == "Test error"
+
+
+# =============================================================================
+# Unit Tests - Pydantic Models
+# =============================================================================
+
+class TestPydanticModels:
+    """Test Pydantic response models."""
+    
+    def test_error_detail_model(self):
+        """ErrorDetail model validates correctly."""
+        detail = ErrorDetail(
+            code="TEST_ERROR",
+            message="Test message",
+            details={"key": "value"}
+        )
+        
+        assert detail.code == "TEST_ERROR"
+        assert detail.message == "Test message"
+        assert detail.details == {"key": "value"}
+    
+    def test_error_detail_optional_details(self):
+        """ErrorDetail allows missing details."""
+        detail = ErrorDetail(code="TEST", message="Test")
+        assert detail.details is None
+    
+    def test_api_success_response_model(self):
+        """ApiSuccessResponse model validates correctly."""
+        response = ApiSuccessResponse(
+            success=True,
+            message="Done",
+            data={"result": 42}
+        )
+        
+        assert response.success is True
+        assert response.message == "Done"
+        assert response.data == {"result": 42}
+    
+    def test_api_error_response_model(self):
+        """ApiErrorResponse model validates correctly."""
+        response = ApiErrorResponse(
+            success=False,
+            error=ErrorDetail(code="ERR", message="Error occurred")
+        )
+        
+        assert response.success is False
+        assert response.error.code == "ERR"
+
+
+# =============================================================================
+# Integration Tests - Exception Handlers
+# =============================================================================
+
+class TestExceptionHandlers:
+    """Test FastAPI exception handlers produce correct responses."""
+    
+    @pytest.fixture
+    def client(self):
+        """Create test client with exception handlers."""
+        from app import app
+        return TestClient(app, raise_server_exceptions=False)
+    
+    def test_http_exception_format(self, client):
+        """HTTPException returns standardized format."""
+        # Access protected route without auth
+        response = client.get("/gemini/jobs")
+        
+        assert response.status_code == 401
+        data = response.json()
+        assert data["success"] is False
+        assert "error" in data
+        assert data["error"]["code"] == "UNAUTHORIZED"
+        assert "message" in data["error"]
+    
+    def test_404_error_format(self, client):
+        """404 errors return standardized format."""
+        response = client.get("/nonexistent-endpoint")
+        
+        assert response.status_code == 404
+        data = response.json()
+        assert data["success"] is False
+        assert data["error"]["code"] == "NOT_FOUND"
+
+
+class TestErrorCodeConstants:
+    """Test ErrorCode constants are defined correctly."""
+    
+    def test_auth_error_codes(self):
+        assert ErrorCode.UNAUTHORIZED == "UNAUTHORIZED"
+        assert ErrorCode.TOKEN_EXPIRED == "TOKEN_EXPIRED"
+        assert ErrorCode.FORBIDDEN == "FORBIDDEN"
+    
+    def test_payment_error_codes(self):
+        assert ErrorCode.INSUFFICIENT_CREDITS == "INSUFFICIENT_CREDITS"
+        assert ErrorCode.PAYMENT_REQUIRED == "PAYMENT_REQUIRED"
+    
+    def test_validation_error_codes(self):
+        assert ErrorCode.VALIDATION_ERROR == "VALIDATION_ERROR"
+        assert ErrorCode.BAD_REQUEST == "BAD_REQUEST"
+    
+    def test_server_error_codes(self):
+        assert ErrorCode.SERVER_ERROR == "SERVER_ERROR"
+        assert ErrorCode.SERVICE_UNAVAILABLE == "SERVICE_UNAVAILABLE"