Create NestJS Exception

Create standardized exceptions following this project's patterns.

Quick Start

When creating an exception:

1. Check if a core exception exists first - Can you reuse NotFoundException, CustomBadRequestException?
2. Determine location - Feature-specific or core/reusable?
3. Follow naming - {Concept}{Action}Exception
4. Use BaseExceptionDto - Required for all exceptions
5. Pick ExceptionTypeEnum - From available types
6. Add Swagger docs - Document in controller

Exception Template

typescript
1// Location:
2// - Feature-specific: src/features/{feature}/exceptions/{exception-name}.exception.ts
3// - Reusable: src/core/exceptions/http/{exception-name}.exception.ts
4
5import { HttpException, HttpStatus } from '@nestjs/common';
6import { ExceptionTypeEnum, BaseExceptionDto } from '@/core/exceptions';
7
8/**
9 * Thrown when [describe specific condition]
10 * 
11 * @example
12 * throw new {ExceptionName}(identifier);
13 */
14export class {ExceptionName} extends HttpException {
15  constructor(identifier: string | number) {
16    const baseExceptionDto = BaseExceptionDto.CreateBaseException(
17      [identifier.toString()],
18      HttpStatus.{STATUS_CODE},
19      ExceptionTypeEnum.{TYPE},
20      '{Detailed error message}',
21    );
22    super(baseExceptionDto, HttpStatus.{STATUS_CODE});
23  }
24}

Available Exception Types

typescript
1ExceptionTypeEnum.BAD_REQUEST           // Invalid request data
2ExceptionTypeEnum.NOT_FOUND             // Resource not found
3ExceptionTypeEnum.VALIDATION            // DTO validation failures
4ExceptionTypeEnum.UNAUTHORIZED          // No authentication
5ExceptionTypeEnum.FORBIDDEN             // Insufficient permissions
6ExceptionTypeEnum.CONFLICT              // Resource conflict
7ExceptionTypeEnum.UNIQUE_VIOLATION      // DB unique constraint
8ExceptionTypeEnum.UNPROCESSABLE_ENTITY  // Cannot process valid request
9ExceptionTypeEnum.INTERNAL_SERVER_ERROR // Server-side errors

Quick Patterns

Not Found

typescript
1export class {Resource}NotFoundException extends HttpException {
2  constructor(id: string) {
3    const baseExceptionDto = BaseExceptionDto.CreateBaseException(
4      [id],
5      HttpStatus.NOT_FOUND,
6      ExceptionTypeEnum.NOT_FOUND,
7      `{Resource} with ID ${id} not found`,
8    );
9    super(baseExceptionDto, HttpStatus.NOT_FOUND);
10  }
11}

Validation with Multiple Fields

typescript
1export class Invalid{Resource}DataException extends HttpException {
2  constructor(fields: string[], detail: string) {
3    const baseExceptionDto = BaseExceptionDto.CreateBaseException(
4      fields,
5      HttpStatus.BAD_REQUEST,
6      ExceptionTypeEnum.VALIDATION,
7      detail,
8    );
9    super(baseExceptionDto, HttpStatus.BAD_REQUEST);
10  }
11}

Business Logic

typescript
1export class {BusinessRule}Exception extends HttpException {
2  constructor(detail: string) {
3    const baseExceptionDto = BaseExceptionDto.CreateBaseException(
4      [],
5      HttpStatus.UNPROCESSABLE_ENTITY,
6      ExceptionTypeEnum.UNPROCESSABLE_ENTITY,
7      detail,
8    );
9    super(baseExceptionDto, HttpStatus.UNPROCESSABLE_ENTITY);
10  }
11}

Reuse Core Exceptions

Always check first: Can you use an existing core exception?

typescript
1import {
2  CustomBadRequestException,
3  NotFoundException,
4  UnauthorizedException,
5  ForbiddenException,
6  DatabaseOperationException,
7} from '@/core/exceptions';
8
9// Generic not found
10throw new NotFoundException('User', userId);
11
12// Generic validation
13throw new CustomBadRequestException(
14  ['email'],
15  ExceptionTypeEnum.VALIDATION,
16  'Invalid email format'
17);

Create custom exceptions only when:

• Core exceptions don't cover the use case
• You need feature-specific error details
• You want better type safety

Swagger Documentation

Always document in controllers:

typescript
1import { ApiCustomExceptionResponse } from '@/core/exceptions';
2
3@Post()
4@ApiCustomExceptionResponse(400, 'Invalid data')
5@ApiCustomExceptionResponse(409, 'Resource conflict')
6async create(@Body() dto: CreateDto) {
7  // Implementation
8}

Checklist

Before creating an exception:

• Checked if core exceptions can be reused
• Determined location (feature-specific or core)
• Name follows {Concept}{Action}Exception format
• Extends HttpException
• Uses BaseExceptionDto.CreateBaseException()
• Includes proper ExceptionTypeEnum
• Has JSDoc with description and example
• Target array specifies relevant fields
• Documented with @ApiCustomExceptionResponse

Rules

❌ NEVER use raw NestJS exceptions:

typescript
1// ❌ WRONG
2throw new BadRequestException('Error');
3throw new NotFoundException('Not found');

✅ ALWAYS use BaseExceptionDto system:

typescript
1// ✅ CORRECT
2throw new NotFoundException('User', userId);
3// Or create custom
4throw new UserNotFoundException(userId);

⚠️ PREFER core exceptions when possible - don't create unnecessary custom exceptions.

Full Documentation

See .cursor/rules/exceptions.mdc for complete rules and patterns.