feat(api): centralized error handling

backend/src/common/errors/app.exception.ts

@@ -54,7 +54,164 @@ export class AppException extends HttpException {
   }
 }
 
-// ─── Convenience subclasses ──────────────────────────────────────────────────
+// ─── Convenience subclasses for new standardized error codes ───────────────────
+
+export class ValidationError extends AppException {
+  constructor(details: ErrorDetail[], message = 'Validation failed') {
+    super({
+      errorCode: AppErrorCode.VALIDATION_ERROR,
+      status: HttpStatus.BAD_REQUEST,
+      message,
+      details,
+      i18nKey: 'errors.validation_failed',
+    });
+  }
+}
+
+export class UnauthorizedException extends AppException {
+  constructor(message = 'Authentication required') {
+    super({
+      errorCode: AppErrorCode.UNAUTHORIZED,
+      status: HttpStatus.UNAUTHORIZED,
+      message,
+      i18nKey: 'errors.unauthorized',
+    });
+  }
+}
+
+export class ForbiddenException extends AppException {
+  constructor(message = 'Insufficient permissions') {
+    super({
+      errorCode: AppErrorCode.FORBIDDEN,
+      status: HttpStatus.FORBIDDEN,
+      message,
+      i18nKey: 'errors.forbidden',
+    });
+  }
+}
+
+export class NotFoundError extends AppException {
+  constructor(resource = 'Resource', message?: string) {
+    super({
+      errorCode: AppErrorCode.NOT_FOUND,
+      status: HttpStatus.NOT_FOUND,
+      message: message || `${resource} not found`,
+      i18nKey: 'errors.not_found',
+    });
+  }
+}
+
+export class ConflictException extends AppException {
+  constructor(message = 'Resource conflict occurred') {
+    super({
+      errorCode: AppErrorCode.CONFLICT,
+      status: HttpStatus.CONFLICT,
+      message,
+      i18nKey: 'errors.conflict',
+    });
+  }
+}
+
+export class RateLimitedException extends AppException {
+  constructor(message = 'Too many requests, please try again later') {
+    super({
+      errorCode: AppErrorCode.RATE_LIMITED,
+      status: HttpStatus.TOO_MANY_REQUESTS,
+      message,
+      i18nKey: 'errors.rate_limited',
+    });
+  }
+}
+
+export class SessionExpiredException extends AppException {
+  constructor(message = 'Your session has expired') {
+    super({
+      errorCode: AppErrorCode.SESSION_EXPIRED,
+      status: HttpStatus.UNAUTHORIZED,
+      message,
+      i18nKey: 'errors.session_expired',
+    });
+  }
+}
+
+export class SessionInvalidException extends AppException {
+  constructor(message = 'Invalid session') {
+    super({
+      errorCode: AppErrorCode.SESSION_INVALID,
+      status: HttpStatus.BAD_REQUEST,
+      message,
+      i18nKey: 'errors.session_invalid',
+    });
+  }
+}
+
+export class ChallengeUnavailableException extends AppException {
+  constructor(message = 'This challenge is currently unavailable') {
+    super({
+      errorCode: AppErrorCode.CHALLENGE_UNAVAILABLE,
+      status: HttpStatus.BAD_REQUEST,
+      message,
+      i18nKey: 'errors.challenge_unavailable',
+    });
+  }
+}
+
+export class InvalidAnswerException extends AppException {
+  constructor(message = 'The provided answer is invalid') {
+    super({
+      errorCode: AppErrorCode.INVALID_ANSWER,
+      status: HttpStatus.BAD_REQUEST,
+      message,
+      i18nKey: 'errors.invalid_answer',
+    });
+  }
+}
+
+export class DuplicateSubmissionException extends AppException {
+  constructor(message = 'You have already submitted an answer for this challenge') {
+    super({
+      errorCode: AppErrorCode.DUPLICATE_SUBMISSION,
+      status: HttpStatus.CONFLICT,
+      message,
+      i18nKey: 'errors.duplicate_submission',
+    });
+  }
+}
+
+export class RewardNotEligibleException extends AppException {
+  constructor(message = 'You are not eligible to receive this reward') {
+    super({
+      errorCode: AppErrorCode.REWARD_NOT_ELIGIBLE,
+      status: HttpStatus.BAD_REQUEST,
+      message,
+      i18nKey: 'errors.reward_not_eligible',
+    });
+  }
+}
+
+export class BlockchainError extends AppException {
+  constructor(message = 'Blockchain operation failed') {
+    super({
+      errorCode: AppErrorCode.BLOCKCHAIN_ERROR,
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      message,
+      i18nKey: 'errors.blockchain_error',
+    });
+  }
+}
+
+export class InternalServerError extends AppException {
+  constructor(message = 'An unexpected internal error occurred') {
+    super({
+      errorCode: AppErrorCode.INTERNAL_SERVER_ERROR,
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      message,
+      i18nKey: 'errors.internal_server_error',
+    });
+  }
+}
+
+// ─── Legacy convenience classes (still supported for backward compatibility) ────
 
 export class ValidationException extends AppException {
   constructor(details: ErrorDetail[], message = 'Validation failed') {
@@ -104,7 +261,7 @@ export class NotFoundException extends AppException {
   }
 }
 
-export class ConflictException extends AppException {
+export class LegacyConflictException extends AppException {
   constructor(message = 'Resource already exists') {
     super({
       errorCode: AppErrorCode.DUPLICATE_RESOURCE,
@@ -140,4 +297,4 @@ export class DatabaseException extends AppException {
       context,
     });
   }
-}
+}

backend/src/common/errors/error-codes.enum.ts

@@ -4,37 +4,58 @@
  * can react without string-matching on human-readable messages.
  */
 export enum AppErrorCode {
+  // ── Validation ───────────────────────────────────────────────────────────────
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+
   // ── Authentication ──────────────────────────────────────────────────────────
+  UNAUTHORIZED = 'UNAUTHORIZED',
+
+  // ── Authorization ────────────────────────────────────────────────────────────
+  FORBIDDEN = 'FORBIDDEN',
+
+  // ── Resource ─────────────────────────────────────────────────────────────────
+  NOT_FOUND = 'NOT_FOUND',
+  CONFLICT = 'CONFLICT',
+
+  // ── Rate Limiting ─────────────────────────────────────────────────────────────
+  RATE_LIMITED = 'RATE_LIMITED',
+
+  // ── Session Errors ─────────────────────────────────────────────────────────────
+  SESSION_EXPIRED = 'SESSION_EXPIRED',
+  SESSION_INVALID = 'SESSION_INVALID',
+
+  // ── Challenge Errors ───────────────────────────────────────────────────────────
+  CHALLENGE_UNAVAILABLE = 'CHALLENGE_UNAVAILABLE',
+  INVALID_ANSWER = 'INVALID_ANSWER',
+  DUPLICATE_SUBMISSION = 'DUPLICATE_SUBMISSION',
+
+  // ── Reward Errors ─────────────────────────────────────────────────────────────
+  REWARD_NOT_ELIGIBLE = 'REWARD_NOT_ELIGIBLE',
+
+  // ── Blockchain Errors ─────────────────────────────────────────────────────────
+  BLOCKCHAIN_ERROR = 'BLOCKCHAIN_ERROR',
+
+  // ── Internal ───────────────────────────────────────────────────────────────────
+  INTERNAL_SERVER_ERROR = 'INTERNAL_SERVER_ERROR',
+
+  // ── Legacy (still supported for backward compatibility) ───────────────────────
   AUTH_TOKEN_EXPIRED = 'AUTH_TOKEN_EXPIRED',
   AUTH_TOKEN_INVALID = 'AUTH_TOKEN_INVALID',
   AUTH_TOKEN_MISSING = 'AUTH_TOKEN_MISSING',
   AUTH_TOKEN_BLACKLISTED = 'AUTH_TOKEN_BLACKLISTED',
   AUTH_INVALID_CREDENTIALS = 'AUTH_INVALID_CREDENTIALS',
   AUTH_USER_NOT_FOUND = 'AUTH_USER_NOT_FOUND',
-
-  // ── Authorization ────────────────────────────────────────────────────────────
   INSUFFICIENT_PERMISSIONS = 'INSUFFICIENT_PERMISSIONS',
   ACCESS_DENIED = 'ACCESS_DENIED',
-
-  // ── Validation ───────────────────────────────────────────────────────────────
   VALIDATION_FAILED = 'VALIDATION_FAILED',
   INVALID_INPUT = 'INVALID_INPUT',
-
-  // ── Resource ─────────────────────────────────────────────────────────────────
   RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
   DUPLICATE_RESOURCE = 'DUPLICATE_RESOURCE',
   RESOURCE_CONFLICT = 'RESOURCE_CONFLICT',
-
-  // ── Rate Limiting ─────────────────────────────────────────────────────────────
   RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
-
-  // ── Database ──────────────────────────────────────────────────────────────────
   DB_CONNECTION_ERROR = 'DB_CONNECTION_ERROR',
   DB_CONSTRAINT_VIOLATION = 'DB_CONSTRAINT_VIOLATION',
   DB_QUERY_FAILED = 'DB_QUERY_FAILED',
-
-  // ── Generic ───────────────────────────────────────────────────────────────────
-  INTERNAL_SERVER_ERROR = 'INTERNAL_SERVER_ERROR',
   SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
   NOT_IMPLEMENTED = 'NOT_IMPLEMENTED',
-}
+}

backend/src/common/errors/index.ts

@@ -1,2 +1,20 @@
 export * from './error-codes.enum';
 export * from './app.exception';
+
+// Re-export the new standardized exceptions for easy importing
+export {
+  ValidationError,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundError,
+  ConflictException,
+  RateLimitedException,
+  SessionExpiredException,
+  SessionInvalidException,
+  ChallengeUnavailableException,
+  InvalidAnswerException,
+  DuplicateSubmissionException,
+  RewardNotEligibleException,
+  BlockchainError,
+  InternalServerError
+} from './app.exception';