Errors & fallback

How gasless failures surface, how to read the vendor’s diagnostics out of them, when a wallet-paid retry is safe, and what to do when a submit’s outcome is simply unknown.

The fallback safety rule

Two predicates encode exactly this — use them instead of re-deriving the rule:

import { isConfirmedGaslessFeeLimitError, isConfirmedGaslessUnavailableError } from "@symmio/trading-core";
 
try {
  await relayInstantOperations(config, parameters);
} catch (err) {
  const safeToUseWallet =
    isConfirmedGaslessFeeLimitError(err) || (!accepted && isConfirmedGaslessUnavailableError(err));
  if (!safeToUseWallet) throw err;
  // …fall back to the gas-paid path
}

Both work on the error a React hook throws too: SymmioRequestError keeps the status and the response body, and every gasless predicate reads them structurally rather than through an instanceof check.

The transparent execution mode applies them for you under fallback: "wallet", with the same exclusions hard-coded: an unconfirmed submit, an idempotency conflict and a 2xx from the wrong protocol instance end the write, whatever fallback says.

One more rejection is safe to retry through the wallet, because it happens before anything is signed: the fee pre-flight finding the daily free quota exhausted (GASLESS_FREE_QUOTA_EXHAUSTED, matched by isGaslessFreeQuotaExhaustedError). The transparent mode falls back on it too. A fee quote that fails for transport reasons is not a rejection: the transparent mode signs and relays anyway, and the relayer’s simulation decides.

The matrix

502 and 504 look like outages and are not treated as one on purpose. The gateway returns 502 for an upstream failure and for a protocol-instance identity mismatch, and either can happen after the body reached the service — which is exactly the shape that produced a double execution when the SDK treated them as “definitely not accepted”.

An ambiguous failure also decides every answer after it. Whatever the SDK’s resend is told — a 429, a gateway 503, even a fee code — describes the resend only, while the first attempt may be executing. So the submit ends as GASLESS_SUBMIT_UNCONFIRMED, never as a rejection a wallet-paid retry may follow.

When the outcome is unknown

A submit that fails ambiguously is resent once by the SDK under the same idempotency key, after a jittered 1–2 s backoff: a resend that races the first attempt’s insert can be answered with a 5xx instead of the record that insert created. If the resend does not land either, however it is answered, the SDK throws GASLESS_SUBMIT_UNCONFIRMED carrying the exact bytes that were sent:

import { getGaslessUnconfirmedSubmit, resubmitGaslessRequest } from "@symmio/trading-core";
 
const pending = getGaslessUnconfirmedSubmit(err);
if (pending) {
  await store.save(pending); // { chainId, service, path, body, idempotencyKey }
  await resubmitGaslessRequest(config, pending);
}

Resending the identical request under the same key either lands it or returns the record the service already created, so it can never double-execute. See resubmitGaslessRequest — and keep the record out of third-party logging, because body holds the user’s signed operations.

Idempotency keys

One key describes one payload. Reuse it only to replay the byte-identical request; change anything — re-sign, add an operation, move a wallet id, settle again after a terminal status — and the key must change too, or the service answers 409 IDEMPOTENCY_KEY_CONFLICT (isGaslessIdempotencyConflictError).

That is why only the actions whose payload you build take an idempotencyKey:

Every acceptance receipt echoes the key that was used, so a relay you did not key yourself is still reconcilable — persist requestId, owner, walletIds and idempotencyKey together.

Reading the vendor detail

HTTP failures are thrown as SymmApiError with the raw response body preserved; parseGaslessErrorDetail digs the vendor’s { code, message, details } envelope out of any gasless error — including whatever the service decoded of an on-chain revert:

import { parseGaslessErrorDetail } from "@symmio/trading-core";
 
const detail = parseGaslessErrorDetail(err);
detail?.code; // "SIMULATION_REVERTED", "INSUFFICIENT_ALLOWANCE", …
detail?.contractRevert?.error; // "InvalidWalletOperationTarget", …
detail?.revertMessage; // "OperationalFee: Insufficient balance"
detail?.decodedRevert; // the service's own decoded view, in whatever shape it sent
detail?.rpcError; // the nested JSON-RPC error, when the failure came from the chain
detail?.failedOperation; // { index, revertData } of an OperationFailed revert
detail?.gatewayError; // "Unknown or disabled protocol instance: …" (the gateway's own { error } body)
detail?.validationErrors; // [{ loc: ["path", "request_id"], msg, type }] (a 422)

revertMessage, decodedRevert, rpcError and failedOperation are read from both detail and detail.details, because deployments differ on which level they use.

contractRevert.arguments is readonly unknown[] | Record<string, unknown>: the vendor sends a positional array or an object keyed by parameter name depending on how it decoded the revert. Narrow with Array.isArray before indexing, or read contractRevert.decoded, which is a plain string on the deployments that key their arguments.

Naming the failing batch entry

A relayed batch is atomic, so the InstantLayer reports an inner failure as OperationFailed(operationIndex, revertData) — a position, not a cause. Decode it against the ABI the failing operation targeted:

import { accountLayerAbi, decodeGaslessOperationFailure } from "@symmio/trading-core";
 
const failure = decodeGaslessOperationFailure(err, accountLayerAbi);
failure?.index; // 1
failure?.decoded?.errorName; // "InvalidNameLength"

Classifying a failure

classifyGaslessFailure reduces any gasless failure to the one reason a UI should act on, reading the decoded revert ahead of the vendor code and the vendor code ahead of the HTTP status — a 400 SIMULATION_REVERTED whose revert names an allowance shortfall is an allowance problem, not a bad request:

import { classifyGaslessFailure } from "@symmio/trading-core";
 
switch (classifyGaslessFailure(err)) {
  case "payer-balance":
    return showTopUp(); // an allowance approval will not fix this
  case "fee-allowance":
    return showApproveOperationalFee();
  case "submit-unconfirmed":
    return showReconcilePending(getGaslessUnconfirmedSubmit(err));
  default:
    return showDiagnostics(parseGaslessErrorDetail(err));
}

Diagnostics for a support report

Capture the environment, protocol instance, service, idempotency key, request id and transaction hash if they exist, the HTTP status and vendor code, and the decoded revert — without credentials.

The error never carries credentials by construction: a gasless HTTP failure keeps no request headers and no request body. Its cause is a sanitized snapshot of the failure (name, message, code, status, method, url), and the URL drops any userinfo and query string.

responseData is a different matter. A FastAPI 422 echoes the rejected input in each detail[].input and ctx — for a missing field that is the whole parent object, which can include the signed operations and their signatures, and a signature the service rejected was never executed, so it stays valid until its deadline. GASLESS_SUBMIT_UNCONFIRMED’s responseData deliberately holds the signed body too. Before sending a gasless error to third-party logging, drop or redact responseData; log a 422 through parseGaslessErrorDetail(err)?.validationErrors, which keeps only loc, msg and type.

Gateway statuses

The gateway answers some failures itself, before any service sees the request, with a { "error": "…" } body instead of the service’s { "detail": … } envelope; parseGaslessErrorDetail(err)?.gatewayError holds that string. Every HTTP failure is a SymmApiError with its status:

retryAfterMs is the Retry-After delay in milliseconds, or null. In a browser it is usually null: a cross-origin page reads Retry-After only when the gateway lists it in Access-Control-Expose-Headers, and by default the gateway exposes only X-GasLessQ-Protocol-Instance. Treat null as unknown, never as “retry now” — the SDK’s own retry waits at least a jittered second either way.

Vendor codes

From the service itself, via parseGaslessErrorDetail(err)?.code:

A FastAPI schema failure returns 422 with no code at all; read validationErrors.

SDK error codes