Class: GSwapSDKError

Error raised by gswap-sdk for validation, gateway, chain, or transaction failures. It is a GalaSDKError (@gala-chain/gala-core-sdk), and can carry any code of the core catalog or of gswap-sdk's own DEX catalog: the signing, transport and wallet failures of a gswap flow are core codes, thrown either as a GSwapSDKError by gswap-sdk or as a plain GalaSDKError by core itself (a signer, the fetch requestor). Catch both with isGSwapError (or core's isGalaError); instanceof GSwapSDKError alone misses the second kind.

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.

Extends

GalaSDKError<C, GSwapErrorParams<C>>

Extended by

AppliedTradeError

Type Parameters

Type Parameter	Default type
`C` extends `GSwapErrorCode`	`GSwapErrorCode`

Constructors

Constructor

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

Parameters

Parameter	Type
`code`	`C`
`params`	`GSwapErrorParams`<`C`>
`context?`	`GalaErrorContext`

Returns

GSwapSDKError<C>

Overrides

GalaSDKError<C, GSwapErrorParams<C>>.constructor

Properties

Property	Modifier	Type	Description	Overrides	Inherited from
`applyTransactionId`	`readonly`	`string` \| `null` \| `undefined`	The transaction id of the apply, when known.	-	`AppliedTradeError`.`applyTransactionId`
`blockNumber`	`readonly`	`number` \| `null` \| `undefined`	The block the apply landed in, when known.	-	`AppliedTradeError`.`blockNumber`
`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.	-	`AppliedTradeError`.`body`
`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.	-	`AppliedTradeError`.`bodyText`
`cause?`	`public`	`unknown`	-	-	`GalaSDKError.cause`
`code`	`readonly`	`C`	The stable, machine-readable code.	-	`GalaSDKError.code`
`message`	`public`	`string`	-	-	`GalaSDKError.message`
`name`	`public`	`string`	-	-	`GalaSDKError.name`
`params`	`readonly`	`P`	The named placeholders of the error: a flat object of primitives, safe to localize with.	-	`GalaSDKError.params`
`phase`	`readonly`	`"post_send"` \| `"in_flight"` \| `"pre_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.	-	`AppliedTradeError`.`phase`
`requestTransactionId`	`readonly`	`string` \| `null` \| `undefined`	The transaction id of the queued request, when known.	-	`AppliedTradeError`.`requestTransactionId`
`retryAfterMs`	`readonly`	`number` \| `undefined`	The server's `Retry-After` in milliseconds (a rate-limited answer), when it sent one.	-	`AppliedTradeError`.`retryAfterMs`
`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.	-	`AppliedTradeError`.`shadow`
`stack?`	`public`	`string`	-	-	`GalaSDKError.stack`
`status`	`readonly`	`number` \| `undefined`	The HTTP status of the response that caused this error, when there was one.	-	`AppliedTradeError`.`status`
`uniqueKey`	`readonly`	`string` \| `undefined`	The `uniqueKey` of the write this error is about, when there is one.	-	`AppliedTradeError`.`uniqueKey`
`url`	`readonly`	`string` \| `undefined`	The URL the failing request went to, when there was one.	-	`AppliedTradeError`.`url`
`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.	-	`AppliedTradeError`.`walletCode`
`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`).	-	`AppliedTradeError`.`write`
`catalog`	`static readonly`	`Readonly`<`Record`<`GSwapErrorCode`, `GalaErrorCatalogEntry`>>	Core's catalog entries and the DEX entries: a `GSwapSDKError` can carry a code of either.	`GalaSDKError.catalog`	-
`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.	-	`GalaSDKError.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

Inherited from

GalaSDKError.[GALA_ERROR_BRAND]

notFound

Get Signature

get notFound(): boolean

True when the failure means "that market, pool or position does not exist" rather than "something went wrong": an HTTP 404, a pair with no pool at any fee tier (NO_POOL_AVAILABLE), or a token the DEX contract has no trading symbol for (UNKNOWN_TOKEN). A pool that exists but is too thin (INSUFFICIENT_LIQUIDITY) is NOT not-found.

Returns

boolean

Overrides

GalaSDKError.notFound

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

GalaSDKError.captureStackTrace

confirmationTimeoutError()

static confirmationTimeoutError(uniqueKey, cause?): GSwapSDKError<"CONFIRMATION_TIMEOUT">

Create the error used when apply-results confirmation does not arrive in time.

Parameters

Parameter	Type
`uniqueKey`	`string`
`cause?`	`unknown`

Returns

GSwapSDKError<"CONFIRMATION_TIMEOUT">

fromChainError()

static fromChainError(errorKey, serverMessage, context?): GSwapSDKError<"CHAIN_REJECTED">

Convert a GalaChain Status: 0 response into a typed SDK error.

Parameters

Parameter	Type
`errorKey`	`string`
`serverMessage`	`string`
`context?`	`GalaErrorContext`

Returns

GSwapSDKError<"CHAIN_REJECTED">

fromErrorResponse()

static fromErrorResponse(url, response): Promise<GSwapSDKError<GSwapErrorCode>>

Convert an unexpected HTTP response into an SDK error.

Parameters

Parameter	Type
`url`	`string`
`response`	`HTTPResponse`

Returns

Promise<GSwapSDKError<GSwapErrorCode>>

fromGatewayBounce()

static fromGatewayBounce(gatewayCode, serverMessage, status, body, url, retryAfterMs?, uniqueKey?): GSwapSDKError

Convert a chain-gateway bounce into a typed SDK error: the gateway's own code when the SDK knows it, GATEWAY_REJECTED (with the code as params.gatewayCode) when it does not. serverMessage is the gateway's English text: for logs, not for a user interface. For CHAIN_DISPATCH_FAILED, params.errorKey is the chain's ErrorKey from the body's top-level errorKey ('' when the gateway sent none): map it, not the text.

Parameters

Parameter	Type
`gatewayCode`	`string`
`serverMessage`	`string`
`status`	`number`
`body`	`unknown`
`url`	`string`
`retryAfterMs?`	`number`
`uniqueKey?`	`string`

Returns

GSwapSDKError

fromStatus()

static fromStatus(status, options?): GSwapSDKError<"HTTP_ERROR" | "UPDATE_REQUIRED">

Builds, synchronously, the error the SDK itself throws for an HTTP answer of this status that has no gateway or chain code: UPDATE_REQUIRED for the version wall (426, whatever else is true), HTTP_ERROR for every other status. It is for an app that holds a resolved HTTP answer the SDK did not read (a v1 endpoint, an interceptor's rejection) and wants the SDK's classification of it (classifyFailure) instead of building the error by hand.

Reads and writes differ exactly as they do in the gateway (classifyFailure): a WRITE carries the signed uniqueKey (the handle to confirm it), a READ carries none. Pass uniqueKey for a write, or write: true with it; write: false builds a read and drops any uniqueKey. write: true without a non-empty uniqueKey throws INVALID_UNIQUE_KEY: a write error with no key would be classified as a read, which is a different answer. Either way an answer was read, so the phase is post_send.

Parameters

Parameter	Type
`status`	`number`
`options?`	`GSwapStatusErrorOptions`

Returns

GSwapSDKError<"HTTP_ERROR" | "UPDATE_REQUIRED">

Example

const read = GSwapSDKError.fromStatus(503, { url });
classifyFailure(read); // { outcome: 'transient', retryable: true }
const write = GSwapSDKError.fromStatus(503, { url, uniqueKey });
classifyFailure(write); // { outcome: 'unknown', retryable: false }: it may have been queued
classifyFailure(GSwapSDKError.fromStatus(426)); // invalid_input: only an update helps

insufficientLiquidityError()

static insufficientLiquidityError(tokenIn, tokenOut, fee?, source?): GSwapSDKError<"INSUFFICIENT_LIQUIDITY">

Create the error used when a pool lacks liquidity for a quote. source as for noPoolAvailableError.

Parameters

Parameter	Type
`tokenIn`	`string` \| `GalaChainTokenClassKey`
`tokenOut`	`string` \| `GalaChainTokenClassKey`
`fee?`	`number`
`source?`	`GSwapSDKError`<`GSwapErrorCode`>

Returns

GSwapSDKError<"INSUFFICIENT_LIQUIDITY">

noPoolAvailableError()

static noPoolAvailableError(tokenIn, tokenOut, fee?, source?): GSwapSDKError<"NO_POOL_AVAILABLE">

Create the error used when no pool can quote the requested pair. source is the backend answer that said so; its status and body are kept.

Parameters

Parameter	Type
`tokenIn`	`string` \| `GalaChainTokenClassKey`
`tokenOut`	`string` \| `GalaChainTokenClassKey`
`fee?`	`number`
`source?`	`GSwapSDKError`<`GSwapErrorCode`>

Returns

GSwapSDKError<"NO_POOL_AVAILABLE">

noSignerError()

static noSignerError(): GSwapSDKError<"NO_SIGNER">

Create the standard missing-signer error.

Returns

GSwapSDKError<"NO_SIGNER">

noWalletAddressError()

static noWalletAddressError(): GSwapSDKError<"NO_WALLET_ADDRESS">

Create the error used when confirming a position write without a configured wallet address.

Returns

GSwapSDKError<"NO_WALLET_ADDRESS">

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

GalaSDKError.prepareStackTrace

unknownTokenError()

static unknownTokenError(token, source?): GSwapSDKError<"UNKNOWN_TOKEN">

Create the error used when a token is not registered by the current DEX contract. source is the backend answer that said so (a quote); its status, body and url are kept.

Parameters

Parameter	Type
`token`	`string` \| `GalaChainTokenClassKey`
`source?`	`GSwapSDKError`<`GSwapErrorCode`>

Returns

GSwapSDKError<"UNKNOWN_TOKEN">

Extends​

Extended by​

Type Parameters​

Constructors​

Constructor​

Parameters​

Returns​

Overrides​

Properties​

Accessors​

[GALA_ERROR_BRAND]​

Get Signature​

Returns​

Inherited from​

notFound​

Get Signature​

Returns​

Overrides​

Methods​

captureStackTrace()​

Parameters​

Returns​

Inherited from​

confirmationTimeoutError()​

Parameters​

Returns​

fromChainError()​

Parameters​

Returns​

fromErrorResponse()​

Parameters​

Returns​

fromGatewayBounce()​

Parameters​

Returns​

fromStatus()​

Parameters​

Returns​

Example​

insufficientLiquidityError()​

Parameters​

Returns​

noPoolAvailableError()​

Parameters​

Returns​

noSignerError()​

Returns​

noWalletAddressError()​

Returns​

prepareStackTrace()​

Parameters​

Returns​

See​

Inherited from​

unknownTokenError()​

Parameters​

Returns​

Extends

Extended by

Type Parameters

Constructors

Constructor

Parameters

Returns

Overrides

Properties

Accessors

[GALA_ERROR_BRAND]

Get Signature

Returns

Inherited from

notFound

Get Signature

Returns

Overrides

Methods

captureStackTrace()

Parameters

Returns

Inherited from

confirmationTimeoutError()

Parameters

Returns

fromChainError()

Parameters

Returns

fromErrorResponse()

Parameters

Returns

fromGatewayBounce()

Parameters

Returns

fromStatus()

Parameters

Returns

Example

insufficientLiquidityError()

Parameters

Returns

noPoolAvailableError()

Parameters

Returns

noSignerError()

Returns

noWalletAddressError()

Returns

prepareStackTrace()

Parameters

Returns

See

Inherited from

unknownTokenError()

Parameters

Returns