HTTPError

Members

Properties

Property	Description
cause	The cause of the error.
code	Stable machine-readable token served in the `code` member, set by HTTPError.id to its first argument
detail	`detail` member of the RFC 9457 problem document, served in place of the error message
headers	Headers merged into `set.headers` when the error is served
message	-
name	-
stack	-
status	HTTP status served when the error reaches the error pipeline, as a number or a status name (`'Payment Required'`)
type	RFC 9457 problem type served in the `type` member, a URI or a slug. Doubles as the tag that discriminates one error class from another
stackTraceLimit	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`).
typeBase	Absolute base for the RFC 9457 `type` URI, applied to every class made by HTTPError.id and to the built-in `ElysiaError`s (`NotFound`, `ParseError`, `InvalidCookie`, `InternalServerError`) both derive `type` from the same slug. Request validation is the exception, it keeps `type: 'validation'` unprefixed

Methods

Method	Description
extension	Return RFC 9457 extension members added to the problem document, synchronously
value	Return a value to serve as the whole response, may be `async`
captureStackTrace	Creates a `.stack` property on `targetObject`, which when accessed returns a string representing the location in the code at which `Error.captureStackTrace()` was called.
id	Create a concrete `HTTPError` subclass carrying `code`, mirrored into `type` unless HTTPError.typeBase is set
isError	Indicates whether the argument provided is a built-in Error instance or not.
prepareStackTrace	-

Defined in: elysia/dist/error.d.ts:271

Self-describing HTTP error

Set status, headers, detail, extension and value to map to response

Send RFC 9457 problem document by default that can be overridden by value()

detail - add detail field to the problem document
extension() - add extension members to the problem document
value() - override the whole response, return problem() to keep the shape

value wins over detail, detail over an extension() string detail, that over message. A value returning undefined falls through to the next one. A response that depends on the request belongs in .onError(Class, handler)

Example

class OutOfCredit extends HTTPError.id('OUT_OF_CREDIT') {
     readonly status = 402
     readonly detail = 'Top up to continue'
}

class Overdrawn extends Error implements HTTPError {
    readonly type = 'OVERDRAWN'
     readonly status = 402

    value() {
        return problem(402, {
             type: 'OVERDRAWN',
              detail: await describeBalance()
         })
    }
}

See

https://www.rfc-editor.org/info/rfc9457

Since

2.0.0

Extends

Error

Type Parameters

Type Parameter	Default type
`T` extends `string`	`string`

Constructors

Constructor

new HTTPError<T>(message?): HTTPError;

Defined in: typescript/lib/lib.es5.d.ts:1080

Parameters

Parameter	Type
`message?`	`string`

Returns

HTTPError

Inherited from

Error.constructor

Constructor

new HTTPError<T>(message?, options?): HTTPError;

Defined in: typescript/lib/lib.es5.d.ts:1080

Parameters

Parameter	Type
`message?`	`string`
`options?`	`ErrorOptions`

Returns

HTTPError

Inherited from

Error.constructor

Constructor

new HTTPError<T>(message?, options?): HTTPError;

Defined in: typescript/lib/lib.es5.d.ts:1080

Parameters

Parameter	Type
`message?`	`string`
`options?`	`ErrorOptions`

Returns

HTTPError

Inherited from

Error.constructor

Properties

cause?

optional cause?: unknown;

Defined in: typescript/lib/lib.es2022.error.d.ts:24

The cause of the error.

Inherited from

Error.cause

code?

readonly optional code?: string;

Defined in: elysia/dist/error.d.ts:287

Stable machine-readable token served in the code member, set by HTTPError.id to its first argument

Unlike type it is never widened to a URI, so it stays the value to dispatch on

detail?

readonly optional detail?: string;

Defined in: elysia/dist/error.d.ts:324

detail member of the RFC 9457 problem document, served in place of the error message

Use value() for anything computed asynchronously

headers?

readonly optional headers?: Record<string, string>;

Defined in: elysia/dist/error.d.ts:311

Headers merged into set.headers when the error is served

message

message: string;

Defined in: typescript/lib/lib.es5.d.ts:1075

Inherited from

Error.message

name

name: string;

Defined in: typescript/lib/lib.es5.d.ts:1074

Inherited from

Error.name

stack?

optional stack?: string;

Defined in: typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.stack

status?

readonly optional status?:
  | number
  | "Continue"
  | "Switching Protocols"
  | "Processing"
  | "Early Hints"
  | "OK"
  | "Created"
  | "Accepted"
  | "Non-Authoritative Information"
  | "No Content"
  | "Reset Content"
  | "Partial Content"
  | "Multi-Status"
  | "Already Reported"
  | "Multiple Choices"
  | "Moved Permanently"
  | "Found"
  | "See Other"
  | "Not Modified"
  | "Temporary Redirect"
  | "Permanent Redirect"
  | "Bad Request"
  | "Unauthorized"
  | "Payment Required"
  | "Forbidden"
  | "Not Found"
  | "Method Not Allowed"
  | "Not Acceptable"
  | "Proxy Authentication Required"
  | "Request Timeout"
  | "Conflict"
  | "Gone"
  | "Length Required"
  | "Precondition Failed"
  | "Payload Too Large"
  | "URI Too Long"
  | "Unsupported Media Type"
  | "Range Not Satisfiable"
  | "Expectation Failed"
  | "I'm a teapot"
  | "Enhance Your Calm"
  | "Misdirected Request"
  | "Unprocessable Content"
  | "Locked"
  | "Failed Dependency"
  | "Too Early"
  | "Upgrade Required"
  | "Precondition Required"
  | "Too Many Requests"
  | "Request Header Fields Too Large"
  | "Unavailable For Legal Reasons"
  | "Internal Server Error"
  | "Not Implemented"
  | "Bad Gateway"
  | "Service Unavailable"
  | "Gateway Timeout"
  | "HTTP Version Not Supported"
  | "Variant Also Negotiates"
  | "Insufficient Storage"
  | "Loop Detected"
  | "Not Extended"
  | "Network Authentication Required";

Defined in: elysia/dist/error.d.ts:309

HTTP status served when the error reaches the error pipeline, as a number or a status name ('Payment Required')

type

abstract type: T;

Defined in: elysia/dist/error.d.ts:279

RFC 9457 problem type served in the type member, a URI or a slug. Doubles as the tag that discriminates one error class from another

On a HTTPError.id class this mirrors code, or resolves to <typeBase>/<code> once HTTPError.typeBase is set

stackTraceLimit

static stackTraceLimit: number;

Defined in: @types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

typeBase?

static optional typeBase?: string;

Defined in: elysia/dist/error.d.ts:304

Absolute base for the RFC 9457 type URI, applied to every class made by HTTPError.id and to the built-in ElysiaErrors (NotFound, ParseError, InvalidCookie, InternalServerError) both derive type from the same slug. Request validation is the exception, it keeps type: 'validation' unprefixed

Example

HTTPError.typeBase = 'https://example.com/errors'

class OutOfCredit extends HTTPError.id('OUT_OF_CREDIT', 402) {}
// → { type: 'https://example.com/errors/OUT_OF_CREDIT',
//     code: 'OUT_OF_CREDIT', … }

Methods

extension()?

optional extension(): Record<string, unknown>;

Defined in: elysia/dist/error.d.ts:350

Return RFC 9457 extension members added to the problem document, synchronously

type, code and status stay the error’s own. A string detail is served when the error has no detail of its own, in place of the message. title and instance may be overridden. Not served when value() answers

Only a plain object’s own data members are served, which types can’t check: return an object literal, not a class instance

Returns

Record<string, unknown>

Example

class OutOfCredit extends HTTPError.id('OUT_OF_CREDIT', 402) {
    constructor(readonly balance: number) {
        super()
    }

    extension() {
        return { balance: this.balance, accounts: ['/account/12345'] }
    }
}

value()?

optional value(): unknown;

Defined in: elysia/dist/error.d.ts:317

Return a value to serve as the whole response, may be async

Supports status()/problem() for status-based Eden response

Returns

unknown

captureStackTrace()

Call Signature

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: @types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

Error.captureStackTrace

Call Signature

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: bun-types/globals.d.ts:1081

Create .stack property on a target object

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

Error.captureStackTrace

id()

Call Signature

static id<Type>(code): TaggedHTTPError<Type>;

Defined in: elysia/dist/error.d.ts:368

Create a concrete HTTPError subclass carrying code, mirrored into type unless HTTPError.typeBase is set

code carries no status annotation, annotate status in the subclass body as a number or a status name

Type Parameters

Type Parameter
`Type` extends `string`

Parameters

Parameter	Type
`code`	`Type`

Returns

TaggedHTTPError<Type>

Example

class OutOfCredit extends HTTPError.id('OUT_OF_CREDIT') {
    override readonly status = 402
    headers = {
        'x-powered-by': 'Elysia'
    }
}

Call Signature

static id<Type, S>(code, status): TaggedHTTPError<Type, {
  status: S extends
     | "Continue"
     | "Switching Protocols"
     | "Processing"
     | "Early Hints"
     | "OK"
     | "Created"
     | "Accepted"
     | "Non-Authoritative Information"
     | "No Content"
     | "Reset Content"
     | "Partial Content"
     | "Multi-Status"
     | "Already Reported"
     | "Multiple Choices"
     | "Moved Permanently"
     | "Found"
     | "See Other"
     | "Not Modified"
     | "Temporary Redirect"
     | "Permanent Redirect"
     | "Bad Request"
     | "Unauthorized"
     | "Payment Required"
     | "Forbidden"
     | "Not Found"
     | "Method Not Allowed"
     | "Not Acceptable"
     | "Proxy Authentication Required"
     | "Request Timeout"
     | "Conflict"
     | "Gone"
     | "Length Required"
     | "Precondition Failed"
     | "Payload Too Large"
     | "URI Too Long"
     | "Unsupported Media Type"
     | "Range Not Satisfiable"
     | "Expectation Failed"
     | "I'm a teapot"
     | "Enhance Your Calm"
     | "Misdirected Request"
     | "Unprocessable Content"
     | "Locked"
     | "Failed Dependency"
     | "Too Early"
     | "Upgrade Required"
     | "Precondition Required"
     | "Too Many Requests"
     | "Request Header Fields Too Large"
     | "Unavailable For Legal Reasons"
     | "Internal Server Error"
     | "Not Implemented"
     | "Bad Gateway"
     | "Service Unavailable"
     | "Gateway Timeout"
     | "HTTP Version Not Supported"
     | "Variant Also Negotiates"
     | "Insufficient Storage"
     | "Loop Detected"
     | "Not Extended"
    | "Network Authentication Required" ? object[S] : S;
}>;

Defined in: elysia/dist/error.d.ts:384

Create a concrete HTTPError subclass carrying code, annotated with status as a number or a status name

Annotate what is served with detail (problem detail member) or value() (whole-response override, may be async)

Type Parameters

Type Parameter

Type extends string

Parameters

Parameter	Type
`code`	`Type`
`status`	`S`

Returns

TaggedHTTPError<Type, { status: S extends | "Continue" | "Switching Protocols" | "Processing" | "Early Hints" | "OK" | "Created" | "Accepted" | "Non-Authoritative Information" | "No Content" | "Reset Content" | "Partial Content" | "Multi-Status" | "Already Reported" | "Multiple Choices" | "Moved Permanently" | "Found" | "See Other" | "Not Modified" | "Temporary Redirect" | "Permanent Redirect" | "Bad Request" | "Unauthorized" | "Payment Required" | "Forbidden" | "Not Found" | "Method Not Allowed" | "Not Acceptable" | "Proxy Authentication Required" | "Request Timeout" | "Conflict" | "Gone" | "Length Required" | "Precondition Failed" | "Payload Too Large" | "URI Too Long" | "Unsupported Media Type" | "Range Not Satisfiable" | "Expectation Failed" | "I'm a teapot" | "Enhance Your Calm" | "Misdirected Request" | "Unprocessable Content" | "Locked" | "Failed Dependency" | "Too Early" | "Upgrade Required" | "Precondition Required" | "Too Many Requests" | "Request Header Fields Too Large" | "Unavailable For Legal Reasons" | "Internal Server Error" | "Not Implemented" | "Bad Gateway" | "Service Unavailable" | "Gateway Timeout" | "HTTP Version Not Supported" | "Variant Also Negotiates" | "Insufficient Storage" | "Loop Detected" | "Not Extended" | "Network Authentication Required" ? object[S] : S; }>

Example

class OutOfCredit extends HTTPError.id('OUT_OF_CREDIT', 402) {}
class Denied extends HTTPError.id('DENIED', 'Payment Required') {
    override readonly detail = 'Top up to continue'
}

isError()

Call Signature

static isError(error): error is Error;

Defined in: typescript/lib/lib.esnext.error.d.ts:21

Indicates whether the argument provided is a built-in Error instance or not.

Parameters

Parameter	Type
`error`	`unknown`

Returns

error is Error

Inherited from

Error.isError

Call Signature

static isError(value): value is Error;

Defined in: bun-types/globals.d.ts:1076

Check if a value is an instance of Error

Parameters

Parameter	Type	Description
`value`	`unknown`	The value to check

Returns

value is Error

True if the value is an instance of Error, false otherwise

Inherited from

Error.isError

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: @types/node/globals.d.ts:56

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace