index/classes/GalaSDKError.md

Error raised by the SDKs for validation, signing, transport, gateway, chain, or transaction failures. Every product SDK's error class (GSwapSDKError, ...) extends it, so error instanceof GalaSDKError (or isGalaError) recognises an error from ANY of them.

Branch on code (stable) and render params through your own localization. message is English generated from the catalog template for logs and developers: it is not stable and must never be shown to a user or matched on.

The class reads a code's template and phase from its static GalaSDKError.catalog: the core catalog here, core's plus a product's own codes on a product subclass. One code is defined in exactly one catalog.

Extends

• Error

Type Parameters

Type Parameter	Default type
C extends string	GalaErrorCode
P	GalaParamsOf<C>

Constructors

Constructor

new GalaSDKError<C, P>(code, params, context?): GalaSDKError<C, P>

Parameters

Parameter	Type
code	C
params	NoInfer<P>
context?	GalaErrorContext

Returns

GalaSDKError<C, P>

Overrides

Error.constructor

Properties

Property	Modifier	Type	Description	Inherited from
applyTransactionId	readonly	string | null | undefined	The transaction id of the apply, when known.	-
blockNumber	readonly	number | null | undefined	The block the apply landed in, when known.	-
body	readonly	unknown	The response body parsed as JSON, when the failing response had one; undefined for a body that was not JSON (see bodyText). Never part of message.	-
bodyText	readonly	string | undefined	The raw text of a failing response whose body was NOT JSON (a proxy's HTML 502, a WAF page, an empty body). It is kept here for diagnostics and is never copied into message, so it cannot reach a user interface by accident.	-
cause?	public	unknown	-	Error.cause
code	readonly	C	The stable, machine-readable code.	-
message	public	string	-	Error.message
name	public	string	-	Error.name
params	readonly	P	The named placeholders of the error: a flat object of primitives, safe to localize with.	-
phase	readonly	"pre_send" | "in_flight" | "post_send"	How far the operation had got when this was thrown, against the request it exists to send (see GalaErrorPhase): pre_send means NOTHING was transmitted, so a write that failed this way cannot have been queued; in_flight means the request left and no answer was read; post_send means an answer was read or the write was already accepted. Every catalog code declares its phase, and a throw site can refine it. A product SDK's failure classifier (gswap-sdk's classifyFailure, isPreSendError) folds it into its answers.	-
requestTransactionId	readonly	string | null | undefined	The transaction id of the queued request, when known.	-
retryAfterMs	readonly	number | undefined	The server's Retry-After in milliseconds (a rate-limited answer), when it sent one.	-
shadow	readonly	boolean	True when this error came from the shadow (dark) path of a product SDK (gswap-sdk's swapShadow, submitSwapShadow, ChainGateway.submitShadow), whatever failed there. The classification is the same as on the public path; this is how an app applies its own dark-swap policy.	-
stack?	public	string	-	Error.stack
status	readonly	number | undefined	The HTTP status of the response that caused this error, when there was one.	-
uniqueKey	readonly	string | undefined	The uniqueKey of the write this error is about, when there is one.	-
url	readonly	string | undefined	The URL the failing request went to, when there was one.	-
walletCode	readonly	string | number | undefined	On SIGNING_FAILED: the code the wallet put on the error its signer threw, when it set one: an EIP-1193 / JSON-RPC number such as 4001 (the person declined) or -32603, or an ethers / viem string such as 'ACTION_REJECTED'. It is read from the cause's own code and is always a short primitive; undefined when the wallet sent none, and on every other code. It is a typed field, not a param: it is data for an app's analytics or its own wallet-specific wording, never part of message, and params.reason stays the stable thing to branch on.	-
write	readonly	boolean	Whether this failure is a WRITE's, as the guards read it: false only for the failure of a READ (a quote, a list, a result read), which has no uniqueKey to confirm and nothing pending, so a 5xx there is transient and retryable. It is true for everything else, and always when uniqueKey is set. That is fail-closed: a failure that does not say it is a read is judged a write, where a 5xx is unknown and never retried. Apps that carry an error through their own wrapper copy this field next to uniqueKey (FailureView.write).	-
catalog	static readonly	Readonly<Record<string, GalaErrorCatalogEntry>>	The catalog this class reads templates and phases from. A product SDK's subclass overrides it with an object holding core's codes AND its own (core's entries are never redefined there).	-
stackTraceLimit	static	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.	Error.stackTraceLimit

Accessors

[GALA_ERROR_BRAND]

Get Signature

get [GALA_ERROR_BRAND](): true

The SDK error brand (Symbol.for('@gala-chain/gala-core-sdk/error')), always true, carried by every product SDK's error class through inheritance. The dependency-free helpers (isWalletUserRejection, isGalaErrorLike) recognise an SDK error by it instead of instanceof, so they work across copies of the SDK and without importing this class. It lives on the prototype: it is not an own property and is never copied or logged.

Returns

true

---

notFound

Get Signature

get notFound(): boolean

True when the failure means "that thing does not exist" rather than "something went wrong": an HTTP 404. A product SDK's subclass adds its own not-found codes (gswap-sdk: no pool, an unknown token).

Returns

boolean

Methods

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.

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

---

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Parameters

Parameter	Type
err	Error
stackTraces	CallSite[]

Returns

any

See

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

Inherited from

Error.prepareStackTrace