[BACKEND-001] Standardize API Response Format and Error Handling

Metadata

Description

Implement a consistent API response format and standardized error handling across all endpoints. Currently, responses vary in structure and error messages are not standardized, making it difficult for frontend clients to handle responses uniformly.

Technical Requirements

  • Create a standard API response wrapper (success/error envelope)
  • Implement consistent error response DTOs with error codes
  • Create custom exception classes for different error types
  • Add HTTP status code constants/enums
  • Implement response interceptors for consistent formatting
  • Document all error codes in OpenAPI spec

Files to Review/Modify

  • /backend/src/main.ts - Global interceptors setup
  • /backend/src/accounts/accounts.controller.ts - Current response patterns
  • /backend/src/highscores/highscores.controller.ts - Current response patterns
  • Create: /backend/src/common/dto/api-response.dto.ts
  • Create: /backend/src/common/interceptors/response.interceptor.ts
  • Create: /backend/src/common/exceptions/ - Custom exceptions

Acceptance Criteria

  • All API responses follow consistent envelope format
  • Error responses include: status, code, message, timestamp
  • Success responses include: status, data, metadata (pagination, etc.)
  • OpenAPI documentation reflects new response format
  • Frontend can reliably parse all API responses
  • Build passes with npm run build
  • Existing tests continue to pass

Implementation Notes

Current response analysis:

  1. Controllers return raw data without wrapper
  2. Validation errors use default NestJS format
  3. No consistent error code system

Recommended response format:

// Success response
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-01-25T00:00:00Z",
    "pagination": { "page": 1, "limit": 25, "total": 100 }
  }
}

// Error response
{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_CREDENTIALS",
    "message": "Invalid username or password",
    "status": 401,
    "timestamp": "2026-01-25T00:00:00Z"
  }
}

Error code categories:

  • AUTH_* - Authentication errors
  • VALIDATION_* - Validation errors
  • RESOURCE_* - Resource not found, etc.
  • SERVER_* - Internal server errors

Implementation approach:

  1. Create response DTOs
  2. Create response interceptor
  3. Create exception filter (for errors)
  4. Apply globally in main.ts

Progress Log