Errors

TODO - Explain the abstract layers within the error, how to create a new decorator, and when to use each one.

API Error

• code
• status
• meta

Composite (Abstract)

Groups multiple API errors.

Bad Request

Filepath: src/
Status: 409

List of Built-in Error Types

• 404 Not Found
• 409 Conflict
• 400 Bad Request

Creating a New Error Type

In src/modules/exceptions/api-errors, there is a list of files. Here, we want to add our new error type. Let's create a new error type for unauthorized access. We create a file unauthorized.api-error.ts. Inside this file, we put the basic configuration of this error type. In most cases, this will set the status code.

export abstract class UnauthorizedApiError extends ApiError {
  @ApiErrorStatus(HttpStatus.UNAUTHORIZED)
  declare status: '401'

  constructor(detail: string) {
    super(detail)
    this.status = '401'
  }
}

After we created a new type we also want to create a new Decorator so swagger knows whats happening in src/modules/exceptions/api-errors/api-error-response.decorator.ts We add a new function ApiUnauthorizedErrorResponse

export function ApiUnauthorizedErrorResponse (
  ...errors: Array<ClassConstructor<UnauthorizedApiError>>
): MethodDecorator {
  return ApiErrorResponse(HttpStatus.UNAUTHORIZED, errors)
}

We can now use this in our errors. We create a new file in our use case with the name of the error we want to throw.

Inside this file, we generate the error. We want a code for the frontend and, if necessary, meta information. Let's create this error together.

export class ClientNotAuthorizedError extends UnauthorizedApiError {
  @ApiErrorCode('client_not_authorized')
  code: 'client_not_authorized'

  meta: never

  constructor(detail?: string) {
    super(detail ?? 'Client is not authorized to execute this code')
    this.code = 'client_not_authorized'
  }
}

This is the most basic way to create an error. In the first line, we extend our newly created ErrorType. Next, we set all the info for Swagger so our documentation knows this error exists. In the constructor, we fill in all the necessary details. We never want meta for this one, so we don't need to fill it in the constructor. We allow you to provide a custom detail with this error. If it's not provided, we set our own.

Let's jump to an example with meta data to give to the frontend.

class ClientIdAlreadyExistsApiErrorMeta {
  @ApiProperty({ type: String })
  id: string

  constructor(id: string) {
    this.id = id
  }
}

export class ClientIdAlreadyExistsError extends ConflictApiError {
  @ApiErrorCode('client_id_already_exists')
  code: 'client_id_already_exists'

  @ApiErrorMeta()
  meta: ClientIdAlreadyExistsApiErrorMeta

  constructor(id: string) {
    super(`Client id ${id} already exists`)
    this.code = 'client_id_already_exists'
    this.meta = new ClientIdAlreadyExistsApiErrorMeta(id)
  }
}

In this example, we declare our meta property. In this case, it's only an ID we want to give to the frontend. You can extend this as much as you like.

After the declaration of the meta data, we create our constructor as previously, but now instead of meta: never, we replace it with @ApiErrorMeta() meta: ClientIdAlreadyExistsApiErrorMeta. This way, Swagger knows exactly what the meta object will look like, and the frontend can see this in the auto-generated docs.

Usage

Throwing an error is fairly straightforward. All we need to do is throw the error where necessary:

if (await this.clientRepo.existsBy({ id: command.id })) {
  throw new ClientIdAlreadyExistsError(command.id);
}

There is only one more thing to do. If we throw an error, we want Swagger to know on which endpoint this error could be thrown. So, we need to put this in our code. On the controller, we add the designated error response decorator. There are also three built-in decorators: @ApiConflictErrorResponse, @ApiBadRequestErrorResponse, and @ApiInternalServerErrorResponse.

@Post()
@ApiCreatedResponse({ type: CreateClientResponse })
@ApiConflictErrorResponse(ClientIdAlreadyExistsError)
async createClient(
  @Body() command: CreateClientCommand
): Promise<CreateClientResponse> {
  return await this.useCase.execute(command);
}