Exception

The @talosjs/exception package gives the framework one consistent way to fail. Instead of throwing bare Error objects, you throw an Exception, a subclass of the native Error that also carries an HTTP status code, an optional grouping key, immutable contextual data, the timestamp it was created, and, when you wrap a native error, the original error. Specialized subclasses like NotFoundException preset the status code so the most common HTTP failures read clearly at the throw site and map straight onto an error response.

What an Exception carries

Every exception carries a status code, defaulting to 500. Those codes come from @talosjs/http-status, so an exception maps directly onto the response it should produce. You can attach a plain object of contextual data (the failing field, an entity id) at the throw site; it is frozen with Object.freeze, so the context that explains the failure cannot be mutated as the error propagates. Each exception also records its creation date, giving logs and error responses an accurate moment of failure without extra bookkeeping. A couple of features help when you need to inspect a failure. stackToJson() parses the raw stack string into a structured ExceptionStackFrameType[] (function name, file, line, column) that you can log or expose in a debug-only response field. And when a third-party call throws a plain Error, you can pass it straight into the constructor: its message is reused and the original is preserved on native, so the underlying stack survives. The specialized subclasses, BadRequestException, NotFoundException, UnauthorizedException, and MethodNotAllowedException, each preset the right status code so intent is obvious where you throw.

How it works

Exception extends Error implements IException. The constructor takes the message (or an Error to wrap) and an options object. It reads status, key, and data, freezes data, sets name to the concrete class name, and, if the message was an Error, stores it on native. The date is captured the moment the instance is created.

Member	Type	Description
`key`	`string \| null`	Optional grouping key for the error (`null` by default).
`date`	`Date`	Timestamp captured when the exception is constructed.
`status`	`StatusCodeType`	HTTP status code; defaults to `500`.
`data`	`Readonly<Record<string, unknown>>`	Frozen contextual data attached at the throw site.
`native`	`Error \| undefined`	The original error, when a native `Error` was wrapped.
`message`	`string`	Error message (inherited from `Error`).
`name`	`string`	The concrete class name, e.g. `"NotFoundException"`.
`stack`	`string \| undefined`	Raw stack trace string (inherited from `Error`).
`stackToJson()`	`ExceptionStackFrameType[] \| null`	Parses `stack` into structured frames, or `null` when no stack exists.

The base constructor signature is:

new Exception(
  message: string | Error,
  options?: {
    key?: string | null;
    status?: StatusCodeType;
    data?: Record<string, unknown>;
  }
)

Each frame returned by stackToJson() matches ExceptionStackFrameType:

type ExceptionStackFrameType = {
  functionName?: string;
  fileName?: string;
  lineNumber?: number;
  columnNumber?: number;
  source: string;
};

The base Exception

Throw an Exception directly when no specialized type fits. With only a message it defaults to status 500 and empty data:

import { Exception } from "@talosjs/exception";

throw new Exception("Something went wrong");

Add a status code and typed contextual data. Both are read straight off the instance later:

import { Exception } from "@talosjs/exception";
import { HttpStatus } from "@talosjs/http-status";

throw new Exception("Validation failed", {
  status: HttpStatus.Code.BadRequest,
  key: "user.email.invalid",
  data: {
    field: "email",
    value: "not-an-email",
    constraint: "Must be a valid email address",
  },
});

The data object is frozen, so reading it downstream is safe. Attempting to mutate it has no effect.

Specialized exceptions

The specialized exceptions extend Exception and preset the status code from @talosjs/http-status. Their constructor is positional: a message, a required key string, and an optional data object (defaults to {}).

new NotFoundException(message: string, key: string, data?: Record<string, unknown>)

Exception	Status code	`HttpStatus.Code`
`BadRequestException`	`400`	`BadRequest`
`UnauthorizedException`	`401`	`Unauthorized`
`NotFoundException`	`404`	`NotFound`
`MethodNotAllowedException`	`405`	`MethodNotAllowed`

import {
  BadRequestException,
  MethodNotAllowedException,
  NotFoundException,
  UnauthorizedException,
} from "@talosjs/exception";

// 404 Not Found
throw new NotFoundException("User not found", "user.not_found", { userId: "123" });

// 400 Bad Request
throw new BadRequestException("Invalid input", "user.invalid", {
  errors: ["email is required", "name is too short"],
});

// 401 Unauthorized
throw new UnauthorizedException("Invalid credentials", "auth.invalid");

// 405 Method Not Allowed
throw new MethodNotAllowedException("POST is not allowed here", "route.method");

Throwing from a service or controller

Throw exceptions where the failure is detected, in a service or a controller, and let the calling layer turn them into a response. Because each exception carries its own status and data, the handler does not need to know how to classify the failure:

import { Exception, NotFoundException } from "@talosjs/exception";
import type { ContextType, IController } from "@talosjs/controller";

export class UserController implements IController {
  public async index(context: ContextType) {
    try {
      const user = await this.findUser(context.params.id);
      return context.response.json({ user });
    } catch (error) {
      if (error instanceof Exception) {
        // status and data travel with the exception
        return context.response.exception(error.message, {
          status: error.status,
          data: error.data,
        });
      }

      throw error;
    }
  }

  private async findUser(id: string) {
    const user = await db.users.find(id);
    if (!user) {
      throw new NotFoundException("User not found", "user.not_found", { id });
    }
    return user;
  }
}

The status and data you attached at the throw site flow straight into the error response. See Response for how context.response.exception(...) and the related helpers serialize this, and Controller for where this handling belongs.

Wrapping a native error

When a third-party call or a built-in throws a plain Error, wrap it instead of swallowing it. Pass the caught error as the message: the constructor reuses its message and keeps the original on native, so the underlying context is never lost:

import { Exception } from "@talosjs/exception";

try {
  JSON.parse(rawConfig);
} catch (error) {
  throw new Exception(error as Error, {
    status: 500,
    data: { context: "Parsing configuration file" },
  });
}

Downstream you can inspect both layers: exception.message and exception.data describe the application-level failure, while exception.native holds the original error and its stack.

Inspecting the stack as JSON

stackToJson() turns the raw stack string into structured frames you can log or filter, rather than a single opaque string:

import { Exception } from "@talosjs/exception";

try {
  throw new Exception("Test error");
} catch (error) {
  if (error instanceof Exception) {
    const frames = error.stackToJson();
    frames?.forEach((frame, index) => {
      console.log(`${index + 1}. ${frame.functionName ?? "<anonymous>"}`);
      console.log(`   at ${frame.fileName}:${frame.lineNumber}:${frame.columnNumber}`);
    });
  }
}

Guidance for throwing well

Throw an Exception (or a specialized subclass) rather than a bare Error, so every failure carries a status code and structured data a handler can act on uniformly. Reach for NotFoundException, BadRequestException, UnauthorizedException, or MethodNotAllowedException when one of them fits; their preset status codes make the intent obvious at the throw site. Put ids, field names, and constraints in data, where they stay machine-readable, and keep the message human-readable. A stable key then lets you classify, route, and translate errors without parsing the message string. Send exceptions to the Logger and use stackToJson() and data for searchable records instead of concatenated strings. Two things to be careful with. Expose stackToJson() only in non-production responses; in production, surface message, status, and safe data and nothing more. And when you catch a native error, wrap it so its message and stack survive on native while you add application context, rather than discarding it.

Getting Started

AI

Framework

Command Line

What an Exception carries

How it works

The base Exception

Specialized exceptions

Throwing from a service or controller

Wrapping a native error

Inspecting the stack as JSON

Guidance for throwing well

​What an Exception carries

​How it works

​The base Exception

​Specialized exceptions

​Throwing from a service or controller

​Wrapping a native error

​Inspecting the stack as JSON

​Guidance for throwing well

What an Exception carries

How it works

The base Exception

Specialized exceptions

Throwing from a service or controller

Wrapping a native error

Inspecting the stack as JSON

Guidance for throwing well