This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk / EnginexError

EnginexError ​

Error thrown by any SDK operation.

Extends ​

  • Error

Constructors ​

Constructor ​

new EnginexError(init): EnginexError

Creates the error from EnginexErrorInit.

Parameters ​

init ​

EnginexErrorInit

Returns ​

EnginexError

Overrides ​

Error.constructor

Properties ​

cause? ​

optional cause?: unknown

Inherited from ​

Error.cause


code ​

readonly code: EnginexErrorCode

Error code; use it with isEnginexError to handle specific cases.


details? ​

readonly optional details?: unknown

Raw map sent by the gateway, with the keys as they came on the wire (e.g. site_key in captcha_required), without conversion to camelCase.


message ​

message: string

Inherited from ​

Error.message


name ​

readonly name: "EnginexError" = 'EnginexError'

Always 'EnginexError'.

Overrides ​

Error.name


requestId? ​

readonly optional requestId?: string

Request identifier for support.


retryAfter? ​

readonly optional retryAfter?: number

Seconds until it can be retried.


stack? ​

optional stack?: string

Inherited from ​

Error.stack


status ​

readonly status: number

HTTP status; 0 for errors without an HTTP response. Exception: UNAUTHENTICATED thrown by the SDK before sending, without a session, uses 401. ABORTED with 0 is cancellation by the caller.


stackTraceLimit ​

static stackTraceLimit: number

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

Methods ​

toJSON() ​

toJSON(): EnginexErrorJSON

Serializable form (used automatically by JSON.stringify). Rebuild with EnginexError.from on the other side (e.g. after crossing a Web Worker, a postMessage or a structured log).

Returns ​

EnginexErrorJSON

Example ​

ts
const json = JSON.stringify(error) // via toJSON()
const revived = EnginexError.from(JSON.parse(json))

toString() ​

toString(): string

Short representation for logs: EnginexError [CODE]: message.

Returns ​

string

Example ​

ts
String(error) // 'EnginexError [INVALID_CREDENTIALS]: wrong password'

captureStackTrace() ​

static captureStackTrace(targetObject, constructorOpt?): void

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

js
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:

js
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 ​

targetObject ​

object

constructorOpt? ​

Function

Returns ​

void

Inherited from ​

Error.captureStackTrace


from() ​

static from(value): EnginexError

Rebuilds an EnginexError from any value, without ever throwing. Rules, in order:

  1. Already an EnginexError: returns the same reference.
  2. Has a string code/message (the output of EnginexError.toJSON, or any similar object) — including an error that is not from the SDK but has its own string code, e.g. a Node error (ECONNREFUSED, ETIMEDOUT): becomes a new EnginexError with those same fields (status/retryAfter only if they are finite numbers; otherwise 0/undefined), keeping the original code. No cause: the source value is already fully represented in the fields.
  3. Anything else becomes UNKNOWN, status: 0, with cause: value and a message limited to 200 characters that never reproduces the contents of an arbitrary object: the message of an Error, the string itself, or the message field of an object (only if it is a string); any other shape (objects without a string message, null, numbers, etc.) becomes the constant 'Unknown error' — never JSON.stringify/String() of the value, which could leak sensitive data (e.g. from({ accessToken: '...' })) or throw (a cyclic value, one with no prototype, or one with a getter that throws). Any property read that throws also falls into this constant fallback.

Parameters ​

value ​

unknown

Returns ​

EnginexError

Example ​

ts
const revived = EnginexError.from(JSON.parse(json))

prepareStackTrace() ​

static prepareStackTrace(err, stackTraces): any

Parameters ​

err ​

Error

stackTraces ​

CallSite[]

Returns ​

any

See ​

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

Inherited from ​

Error.prepareStackTrace