Function: classifyFailure()

gSwap SDK 2.0.0-rc.4

---

gSwap SDK 2.0.0-rc.4 / classifyFailure

Function: classifyFailure()

classifyFailure(error, options?): FailureClassification

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

Classifies any thrown value from its code (and, for a few codes, its HTTP status), never from message text, so an app does not have to re-derive "may I offer Retry?" and "is the outcome unknown?" for every code. The decision for each code is in this module's table; a new catalog code cannot be added without one.

A failure BEFORE the request left (error.phase === 'pre_send', isPreSendError) can never be unknown or rejected: it is invalid_input (the input has to change) or not_sent (nothing was transmitted; a repeat is safe). Every app-supplied callback the SDK calls before it sends (the signer, the key provider, a token resolver) has its failure wrapped into such an error (SIGNING_FAILED, KEY_PROVIDER_FAILED, TOKEN_RESOLUTION_FAILED, the original as cause), so an app NEVER needs an error class of its own to say "nothing was sent": a locked wallet, a declined signature and a failed lookup all arrive as not_sent, retryable.

It accepts a GSwapSDKError or a plain-object VIEW of one (FailureView: { code, params?, status?, uniqueKey?, ... }, the shape of the wrapper an app builds from an SDK error; toFailureView reads any value), and decides from the same fields, so an app does not need to keep the original error to ask. { afterQueued: true } says the write is already queued (the step being classified is a confirmation): retryable is then always false.

Anything that is not an SDK error or such a view, or a view whose code the catalog does not define, is { outcome: 'unknown', retryable: false }: the SDK cannot say what happened, and refusing Retry is the safe answer. That is only what escapes AFTER the request left (an app requestor that rejects with its own error, a callback of yours that throws once bytes were sent). An error your own code raises BEFORE it calls the SDK says so itself: give it a code of its own and outcome ({ code: 'POSITION_STALE', outcome: 'not_sent' }), and the SDK answers with that outcome's classification and mayHaveBeenQueued is false. The declared outcome is read only for a code the catalog does not define.

A failure is a WRITE's unless it states write: false (GSwapSDKError.write, set for every SDK read): see FailureView. A view that lost its uniqueKey is therefore still judged as a write (a 5xx stays unknown), never as a retryable read.

To learn that a failure came from the dark (shadow) path, read error.shadow (a typed field of every GSwapSDKError) or call isShadowError(error), which also covers a non-SDK object that escaped swapShadow / submitSwapShadow / ChainGateway.submitShadow. The classification is the same as on the public path; an app that withholds Retry or a public fallback after a dark swap applies that policy on top of retryable.

Parameters

error

unknown

options?

ClassifyFailureOptions

Returns

FailureClassification

Example

try {
  await swaps.swap('GALA', 'GUSDC', 3000, { exactIn: '100' });
} catch (error) {
  const { outcome, retryable } = classifyFailure(error);
  if (outcome === 'unknown') keepPendingAndConfirm(error); // never a second swap
  else if (retryable) offerRetry(); // a new request under a fresh key
}