Skip to main content

Class: GSwapSDKError\<C\>

gSwap SDK 2.0.0-rc.4

gSwap SDK 2.0.0-rc.4 / GSwapSDKError

Class: GSwapSDKError<C>

Defined in: packages/gswap-sdk/dist/index.d.ts:938

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​

Extended by​

Type Parameters​

C​

C extends GSwapErrorCode = GSwapErrorCode

Constructors​

Constructor​

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

Defined in: packages/gswap-sdk/dist/index.d.ts:941

Parameters​

code​

C

params​

GSwapErrorParams<C>

context?​

GalaErrorContext

Returns​

GSwapSDKError<C>

Overrides​

GalaSDKError<C, GSwapErrorParams<C>>.constructor

Properties​

applyTransactionId​

readonly applyTransactionId: string | null | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1181

The transaction id of the apply, when known.

Inherited from​

AppliedTradeError.applyTransactionId

blockNumber​

readonly blockNumber: number | null | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1183

The block the apply landed in, when known.

Inherited from​

AppliedTradeError.blockNumber

body​

readonly body: unknown

Defined in: packages/gala-core-sdk/dist/index.d.ts:1167

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.

Inherited from​

AppliedTradeError.body

bodyText​

readonly bodyText: string | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1173

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.

Inherited from​

AppliedTradeError.bodyText

cause?​

optional cause?: unknown

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from​

GalaSDKError.cause

code​

readonly code: C

Defined in: packages/gala-core-sdk/dist/index.d.ts:1156

The stable, machine-readable code.

Inherited from​

GalaSDKError.code

message​

message: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from​

GalaSDKError.message

name​

name: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074

Inherited from​

GalaSDKError.name

params​

readonly params: P

Defined in: packages/gala-core-sdk/dist/index.d.ts:1158

The named placeholders of the error: a flat object of primitives, safe to localize with.

Inherited from​

GalaSDKError.params

phase​

readonly phase: "post_send" | "in_flight" | "pre_send"

Defined in: packages/gala-core-sdk/dist/index.d.ts:1192

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.

Inherited from​

AppliedTradeError.phase

requestTransactionId​

readonly requestTransactionId: string | null | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1179

The transaction id of the queued request, when known.

Inherited from​

AppliedTradeError.requestTransactionId

retryAfterMs​

readonly retryAfterMs: number | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1160

The server's Retry-After in milliseconds (a rate-limited answer), when it sent one.

Inherited from​

AppliedTradeError.retryAfterMs

shadow​

readonly shadow: boolean

Defined in: packages/gala-core-sdk/dist/index.d.ts:1199

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.

Inherited from​

AppliedTradeError.shadow

stack?​

optional stack?: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from​

GalaSDKError.stack

status​

readonly status: number | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1162

The HTTP status of the response that caused this error, when there was one.

Inherited from​

AppliedTradeError.status

uniqueKey​

readonly uniqueKey: string | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1177

The uniqueKey of the write this error is about, when there is one.

Inherited from​

AppliedTradeError.uniqueKey

url​

readonly url: string | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1175

The URL the failing request went to, when there was one.

Inherited from​

AppliedTradeError.url

walletCode​

readonly walletCode: string | number | undefined

Defined in: packages/gala-core-sdk/dist/index.d.ts:1217

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.

Inherited from​

AppliedTradeError.walletCode

write​

readonly write: boolean

Defined in: packages/gala-core-sdk/dist/index.d.ts:1208

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).

Inherited from​

AppliedTradeError.write

catalog​

readonly static catalog: Readonly<Record<GSwapErrorCode, GalaErrorCatalogEntry>>

Defined in: packages/gswap-sdk/dist/index.d.ts:940

Core's catalog entries and the DEX entries: a GSwapSDKError can carry a code of either.

Overrides​

GalaSDKError.catalog

stackTraceLimit​

static stackTraceLimit: number

Defined in: node_modules/.pnpm/@types+node@26.6.5/node_modules/@types/node/globals.d.ts:67

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​

GalaSDKError.stackTraceLimit

Accessors​

[GALA_ERROR_BRAND]​

Get Signature​

get [GALA_ERROR_BRAND](): true

Defined in: packages/gala-core-sdk/dist/index.d.ts:1226

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

Defined in: packages/gswap-sdk/dist/index.d.ts:949

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

Defined in: node_modules/.pnpm/@types+node@26.6.5/node_modules/@types/node/globals.d.ts:51

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​

targetObject​

object

constructorOpt?​

Function

Returns​

void

Inherited from​

GalaSDKError.captureStackTrace

confirmationTimeoutError()​

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

Defined in: packages/gswap-sdk/dist/index.d.ts:977

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

Parameters​

uniqueKey​

string

cause?​

unknown

Returns​

GSwapSDKError<"CONFIRMATION_TIMEOUT">

fromChainError()​

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

Defined in: packages/gswap-sdk/dist/index.d.ts:970

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

Parameters​

errorKey​

string

serverMessage​

string

context?​

GalaErrorContext

Returns​

GSwapSDKError<"CHAIN_REJECTED">

fromErrorResponse()​

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

Defined in: packages/gswap-sdk/dist/index.d.ts:1003

Convert an unexpected HTTP response into an SDK error.

Parameters​

url​

string

response​

HTTPResponse

Returns​

Promise<GSwapSDKError<GSwapErrorCode>>

fromGatewayBounce()​

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

Defined in: packages/gswap-sdk/dist/index.d.ts:968

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​

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">

Defined in: packages/gswap-sdk/dist/index.d.ts:1001

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​

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">

Defined in: packages/gswap-sdk/dist/index.d.ts:960

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

Parameters​

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">

Defined in: packages/gswap-sdk/dist/index.d.ts:958

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​

tokenIn​

string | GalaChainTokenClassKey

tokenOut​

string | GalaChainTokenClassKey

fee?​

number

source?​

GSwapSDKError<GSwapErrorCode>

Returns​

GSwapSDKError<"NO_POOL_AVAILABLE">

noSignerError()​

static noSignerError(): GSwapSDKError<"NO_SIGNER">

Defined in: packages/gswap-sdk/dist/index.d.ts:951

Create the standard missing-signer error.

Returns​

GSwapSDKError<"NO_SIGNER">

noWalletAddressError()​

static noWalletAddressError(): GSwapSDKError<"NO_WALLET_ADDRESS">

Defined in: packages/gswap-sdk/dist/index.d.ts:953

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

Defined in: node_modules/.pnpm/@types+node@26.6.5/node_modules/@types/node/globals.d.ts:55

Parameters​

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">

Defined in: packages/gswap-sdk/dist/index.d.ts:975

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​

token​

string | GalaChainTokenClassKey

source?​

GSwapSDKError<GSwapErrorCode>

Returns​

GSwapSDKError<"UNKNOWN_TOKEN">