Skip to content

Error Handling

Handle every failure mode of the Glide SDK

Every error the SDK throws is a typed error class exported from @paywithglide/glide-js, so you can branch on failure modes with instanceof:

import {
  createSession,
  executeEVMSession,
  NoPaymentOptionsError,
  SessionExpiredError,
  SponsoredTransactionFailedError,
  InsufficientPaymentAmountError,
} from "@paywithglide/glide-js";
 
try {
  const session = await createSession(config, { ... });
  await executeEVMSession(config, { session, ... });
} catch (e) {
  if (e instanceof NoPaymentOptionsError) {
    // The user has no balance that can cover this transaction
  } else if (e instanceof SessionExpiredError) {
    // Create a fresh session and let the user retry
  } else if (e instanceof InsufficientPaymentAmountError) {
    // The amount paid was too low; the payment will be refunded
  } else if (e instanceof SponsoredTransactionFailedError) {
    // Settlement failed; contact Glide support with the session ID
  } else {
    // The user rejected in their wallet, a network error, etc.
    throw e;
  }
}

Error reference

Session lifecycle

SessionExpiredError — the session expired (or is within 30 seconds of expiring) before the payment was completed. Thrown by executeEVMSession, executeSolanaSession, and waitForSession. Recovery: create a new session and let the user retry — quotes are only valid for the session's lifetime.

SponsoredTransactionFailedError — the settlement transaction on the destination chain failed. Thrown by waitForSession (and the execute actions, which wait internally). Recovery: this is rare and terminal for the session; surface it to the user and contact Glide support with the session ID.

InsufficientPaymentAmountError — the amount paid doesn't cover the required payment amount, and the payment is queued for refund (paymentStatus becomes pending_refund). Thrown by waitForSession, payWithTransfer, and other actions when the backend reports it. Recovery: the payer is refunded automatically; create a new session for another attempt.

PaymentPendingError — the payment hasn't been detected or confirmed yet. Thrown by payWithTransfer, payWithCoinbaseOnramp, and payWithCoinbaseApp. Recovery: retry after a short delay — waitForTransfer does exactly this loop for you.

TransactionNotFoundError — the payment transaction hash can't be found on chain yet. Thrown by updatePaymentTransaction and the pay actions. Recovery: the transaction may not have propagated yet; retry with a short delay (the execute actions retry this for up to a minute internally).

Session creation

NoPaymentOptionsError — thrown by createSession when no paymentCurrency was specified and the user has no balance that can cover the transaction. Recovery: prompt the user to fund their wallet, or use listPaymentOptions with includeInsufficientBalanceOptions: true to show what they could pay with.

GlideOverCapacityError — Glide is temporarily over capacity for the requested route. Recovery: retry later.

CurrencyNotSupportedError — thrown by a currency's on(chain) or contractAddressOn(chain) helper when the currency doesn't exist on that chain. Recovery: only offer chain and currency combinations returned by listSupportedCurrencies.

Transport

ResponseNotOkError — the catch-all for any non-OK API response that doesn't map to a more specific error. It exposes statusCode (the HTTP status) and response (the raw body) for debugging:

if (e instanceof ResponseNotOkError) {
  console.error("Glide API error", e.statusCode, e.response);
}

Recovery: a 4xx usually means invalid parameters — check response for the reason; a 5xx is safe to retry.

Wallet errors

Errors from the user's wallet — rejecting a transaction or signature, or failing to switch chains — are thrown by the callbacks you pass to executeEVMSession/executeSolanaSession (e.g., wagmi's UserRejectedRequestError), not by Glide. Handle them alongside the Glide errors in your catch block; the session remains valid until it expires, so the user can simply retry.