Skip to main content

Exception Utilities

Standard HTTP and general error handling.

Overview​

This module provides a set of classes and utility functions for consistent error handling in HTTP APIs.
It includes custom exception classes for common HTTP status codes, type guards, error factories, and error handling wrappers.

API Summary​

Types & Interfaces​

// Base error response interface
export class ErrorResponse extends Error {
  message: string;
  error: boolean;
  timestamp: string;
  requestId: string;
  status: number;
}

export interface ApiErrorResponse extends ErrorResponse {
  path?: string;
  stack?: string[];
}

Function Documentation & Usage Examples​

HttpError​

Generic HTTP error class for custom exceptions with any status code.

Method Signature:

class HttpError extends ErrorResponse { constructor(status: number, message: string); }

Parameters:

  • status (number): HTTP status code (e.g., 404, 500).
  • message (string): Error message.

Throws:

  • An instance of HttpError.

Example:

import { HttpError } from '@catbee/utils';

throw new HttpError(401, "Unauthorized access");

InternalServerErrorException​

Represents a 500 Internal Server Error.

Method Signature:

class InternalServerErrorException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Internal Server Error".

Throws:

  • An instance of InternalServerErrorException.

Example:

import { InternalServerErrorException } from '@catbee/utils';

throw new InternalServerErrorException();

UnauthorizedException​

Represents a 401 Unauthorized Error.

Method Signature:

class UnauthorizedException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Unauthorized".

Throws:

  • An instance of UnauthorizedException.

Example:

import { UnauthorizedException } from '@catbee/utils';

throw new UnauthorizedException("Login required");

BadRequestException​

Represents a 400 Bad Request Error.

Method Signature:

class BadRequestException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Bad Request".

Throws:

  • An instance of BadRequestException.

Example:

import { BadRequestException } from '@catbee/utils';

throw new BadRequestException("Invalid input");

NotFoundException​

Represents a 404 Not Found Error.

Method Signature:
class NotFoundException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Not Found".

Throws:

  • An instance of NotFoundException.

Example:

import { NotFoundException } from '@catbee/utils';

throw new NotFoundException("User not found");

ForbiddenException​

Represents a 403 Forbidden Error.

Method Signature:
class ForbiddenException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Forbidden".

Throws:

  • An instance of ForbiddenException.

Example:

import { ForbiddenException } from '@catbee/utils';

throw new ForbiddenException();

ConflictException​

Represents a 409 Conflict Error.

Method Signature:

class ConflictException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Conflict".

Throws:

  • An instance of ConflictException.

Example:

import { ConflictException } from '@catbee/utils';

throw new ConflictException("Resource already exists");

BadGatewayException​

Represents a 502 Bad Gateway Error.

Method Signature:

class BadGatewayException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Bad Gateway".

Throws:

  • An instance of BadGatewayException.

Example:

import { BadGatewayException } from '@catbee/utils';

throw new BadGatewayException();

TooManyRequestsException​

Represents a 429 Too Many Requests Error.

Method Signature:

class TooManyRequestsException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Too Many Requests".

Throws:

  • An instance of TooManyRequestsException.

Example:

import { TooManyRequestsException } from '@catbee/utils';

throw new TooManyRequestsException();

ServiceUnavailableException​

Represents a 503 Service Unavailable Error.

Method Signature:

class ServiceUnavailableException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Service Unavailable".

Throws:

  • An instance of ServiceUnavailableException.

Example:

import { ServiceUnavailableException } from '@catbee/utils';

throw new ServiceUnavailableException();

GatewayTimeoutException​

Represents a 504 Gateway Timeout Error.

Method Signature:

class GatewayTimeoutException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Gateway Timeout".

Throws:

  • An instance of GatewayTimeoutException.

Example:

import { GatewayTimeoutException } from '@catbee/utils';

throw new GatewayTimeoutException();

UnprocessableEntityException​

Represents a 422 Unprocessable Entity Error.

Method Signature:

class UnprocessableEntityException extends ErrorResponse { constructor(message?: string, details?: Record<string, any>) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Unprocessable Entity".
  • details (object, optional): Additional error details.

Example:

import { UnprocessableEntityException } from '@catbee/utils';

throw new UnprocessableEntityException("Validation failed", { field: "email" });

MethodNotAllowedException​

Represents a 405 Method Not Allowed Error.

Method Signature:

class MethodNotAllowedException extends ErrorResponse { constructor(message?: string, allowedMethods?: string[]) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Method Not Allowed".
  • allowedMethods (string[], optional): List of allowed HTTP methods.

Throws:

  • An instance of MethodNotAllowedException.

Example:

import { MethodNotAllowedException } from '@catbee/utils';

throw new MethodNotAllowedException("Use GET", ["GET"]);

NotAcceptableException​

Represents a 406 Not Acceptable Error.

Method Signature:

class NotAcceptableException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Not Acceptable".

Throws:

  • An instance of NotAcceptableException.

Example:

import { NotAcceptableException } from '@catbee/utils';

throw new NotAcceptableException();

RequestTimeoutException​

Represents a 408 Request Timeout Error.

Method Signature:

class RequestTimeoutException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Request Timeout".

Throws:

  • An instance of RequestTimeoutException.

Example:

import { RequestTimeoutException } from '@catbee/utils';

throw new RequestTimeoutException();

UnsupportedMediaTypeException​

Represents a 415 Unsupported Media Type Error.

Method Signature:

class UnsupportedMediaTypeException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Unsupported Media Type".

Throws:

  • An instance of UnsupportedMediaTypeException.

Example:

import { UnsupportedMediaTypeException } from '@catbee/utils';

throw new UnsupportedMediaTypeException();

PayloadTooLargeException​

Represents a 413 Payload Too Large Error.

Method Signature:

class PayloadTooLargeException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Payload Too Large".

Throws:

  • An instance of PayloadTooLargeException.

Example:

import { PayloadTooLargeException } from '@catbee/utils';

throw new PayloadTooLargeException();

InsufficientStorageException​

Represents a 507 Insufficient Storage Error.

Method Signature:

class InsufficientStorageException extends ErrorResponse { constructor(message?: string) }

Parameters:

  • message (string, optional): Custom error message. Defaults to "Insufficient Storage".

Throws:

  • An instance of InsufficientStorageException.

Example:

import { InsufficientStorageException } from '@catbee/utils';

throw new InsufficientStorageException();

isHttpError()​

Checks if an error is an instance of HttpError or its subclasses.

Method Signature:

function isHttpError(error: unknown): error is ErrorResponse

Parameters:

  • error (unknown): The error to check.

Returns:

  • boolean: True if the error is an instance of HttpError or its subclasses.

Example:

import { isHttpError } from '@catbee/utils';

if (isHttpError(err)) { /* handle HTTP error */ }

createHttpError()​

Creates an HTTP error with the specified status code and message.

Method Signature:

function createHttpError(status: number, message?: string): ErrorResponse

Parameters:

  • status (number): HTTP status code.
  • message (string, optional): Custom error message.

Returns:

  • An instance of ErrorResponse corresponding to the status code.

Example:

import { createHttpError } from '@catbee/utils';

throw createHttpError(404, "Not found");

hasErrorShape()​

Type guard to check if an object has specific error properties.

Method Signature:

function hasErrorShape(error: unknown): error is { message: string; status?: number; code?: string }

Parameters:

  • error (unknown): The object to check.

Returns:

  • boolean: True if the object has the error shape.

Example:

import { hasErrorShape } from '@catbee/utils';

if (hasErrorShape(err)) { console.log(err.message); }

getErrorMessage()​

Safely extracts message from any error type.

Method Signature:

function getErrorMessage(error: unknown): string

Parameters:

  • error (unknown): The error from which to extract the message.

Returns:

  • string: The extracted error message or a default message.

Example:

import { getErrorMessage } from '@catbee/utils';

const msg = getErrorMessage(err);

withErrorHandling()​

Wraps a function and transforms any errors into HTTP errors.

Method Signature:

function withErrorHandling<T extends (...args: any[]) => Promise<any>>(handler: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>

Parameters:

  • handler (function): The async function to wrap.

Returns:

  • A new function that wraps the original and handles errors.

Example:

import { withErrorHandling } from '@catbee/utils';

const safeHandler = withErrorHandling(async (req) => {
  // ...handler code...
});