Handle errors from the Trustware SDK

Most SDK errors are a typed TrustwareError. Routing failures, rate limits, and a few validation checks use their own classes or a plain Error, covered below. You can handle errors reactively via the onError callback, imperatively by catching thrown errors in the headless core, or by listening for the error event in the lifecycle events stream.

The `TrustwareError` class

TrustwareError extends the native Error class with three additional fields:

Field	Type	Description
`code`	`TrustwareErrorCode`	Machine-readable error code; use this for branching logic
`message`	`string`	Technical description of the error
`userMessage`	`string \| undefined`	Optional human-readable message suitable for display
`cause`	`unknown \| undefined`	The original error that triggered this one, if any

Import it directly from the SDK:

import { TrustwareError } from "@trustware/sdk";

Error codes

The TrustwareErrorCode enum lists the codes a TrustwareError can carry.

Code	Typical cause
`INVALID_CONFIG`	The configuration object is missing required fields or has an invalid value
`INVALID_API_KEY`	The API key was rejected; thrown during `Trustware.init()`
`WALLET_NOT_CONNECTED`	A wallet operation was attempted before a wallet was connected
`BRIDGE_FAILED`	The cross-chain bridge transaction could not be completed
`NETWORK_ERROR`	A network request failed (timeout, DNS failure, or server error)
`INPUT_ERROR`	The input to a core method (amount, address, etc.) is invalid
`UNKNOWN_ERROR`	An unexpected error with no more specific classification

INVALID_API_KEY is thrown synchronously during initialization. Make sure to handle it at startup rather than only in your per-transaction error handler.

Handling errors via `onError`

Pass an onError callback in your TrustwareConfigOptions to receive all errors emitted by the widget and provider. This is the simplest approach for most integrations.

import { TrustwareProvider, type TrustwareConfigOptions } from "@trustware/sdk";

const config = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  },
  onError: (error) => {
    console.error(error.code, error.message);
  },
} satisfies TrustwareConfigOptions;

If you want to display a user-friendly message instead of a raw technical error, use error.userMessage when it is defined:

onError: (error) => {
  const display = error.userMessage ?? "Something went wrong. Please try again.";
  showErrorBanner(display);
},

In production, log error.code and error.message to your error tracking service and display error.userMessage to users. This gives you diagnostic detail without exposing internal error strings.

Handling errors with try/catch

When using the headless core API, errors are thrown as exceptions. Wrap core calls in a try/catch block.

import { Trustware, TrustwareError, TrustwareErrorCode } from "@trustware/sdk";

try {
  const route = await Trustware.buildRoute({
    fromChain: "1",
    toChain: "8453",
    fromToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    fromAmount: "1000000",
    fromAddress: await Trustware.getAddress(),
    toAddress: "0xDestination...",
  });
} catch (error) {
  if (error instanceof TrustwareError) {
    if (error.code === TrustwareErrorCode.WALLET_NOT_CONNECTED) {
      promptWalletConnection();
    } else {
      console.error(error.code, error.message);
    }
  }
}

Errors that are not `TrustwareError`

Some SDK rejections are not a TrustwareError, so an instanceof TrustwareError check will not match them. Check the exported classes, such as RouteExpiredError, ReceiptCommitError, and RateLimitError, with instanceof, and a RouteError with isRouteError(). Match by name or by message only for a plain Error that has no exported class.

Destination posthook validation

Trustware.buildRoute() and Trustware.buildDepositAddress() reject a structurally incomplete hooks.postHook before sending the request.

Cause	Message
`target` missing or blank	`hooks.postHook.target is required.`
`callData` missing or blank	`hooks.postHook.callData is required.`
`fullAmount` set without `amountInputPos`	`hooks.postHook.amountInputPos is required when fullAmount is true.`
Neither `fundAmount` nor `fullAmount` set	`hooks.postHook.fundAmount is required unless fullAmount is set.`

fullAmount and amountInputPos are provider dependent. See amount patching. These checks confirm the request is complete. They do not verify that your calldata is correct, that target is a contract, or that the destination call will succeed. The API is authoritative for everything the client cannot check, and rejects a posthook it will not route with a 400 and a message describing the problem. See vault destinations.

Source token approvals

Trustware.sendRouteTransaction() can submit ERC-20 approvals before the route transaction. Four failures can surface from that step.

Cause	Message or name
The approval transaction reverted on chain	`Approval transaction reverted`
The approval did not confirm in time	`Timed out waiting for approval confirmation`
The approval never appeared on its chain, which usually means the wallet sent it on a different network	`Approval transaction <hash> was not found on chain <chainId>.`, followed by a hint to check the wallet’s network
An approval transaction-status lookup failed	an `Error` whose `name` is `"SDKRPCError"`

All four are recoverable. Let the user retry rather than treating the deposit as failed.

import { Trustware, TrustwareError } from "@trustware/sdk";

try {
  const route = await Trustware.buildRoute({ /* ... */ });
  const txHash = await Trustware.sendRouteTransaction(route, 1);
  await Trustware.submitReceipt(route.intentId, txHash);
} catch (error) {
  if (error instanceof TrustwareError) {
    handleSdkError(error.code, error.message);
    return;
  }

  if (error instanceof Error && error.name === "SDKRPCError") {
    retryDeposit();
    return;
  }

  // Posthook validation and approval failures land here.
  handlePlainError(error instanceof Error ? error.message : String(error));
}

SDKRPCError is not exported from the package, so identify it by error.name rather than with instanceof.

Route approvals with no usable amount

Trustware.buildRoute() throws a plain Error when a route.execution.approvals entry has an amount that is missing or not a whole number. Requires SDK 1.1.18 or later.

Cause	Message
`amount` missing or empty	`Route approval <index> (spender <spender>) has no amount.`
`amount` not a whole number	`Route approval <index> (spender <spender>) has an invalid amount "<amount>".`

Treat it like any other failed build and let the user try again.

Expired routes

Trustware.sendRouteTransaction(), Trustware.sendReviewedRoute(), and sendRouteAsUserOperation() throw RouteExpiredError when the route’s expiresAt has passed. The route transaction was not sent, but approvals that already confirmed stay on chain. Build a new route. On a Solana route, sendReviewedRoute() checks the route it rebuilds right before signing, not the one you reviewed. Requires SDK 1.1.18 or later.

import { RouteExpiredError, Trustware } from "@trustware/sdk";

try {
  const txHash = await Trustware.sendRouteTransaction(route, 1);
  await Trustware.submitReceipt(route.intentId, txHash);
} catch (error) {
  if (error instanceof RouteExpiredError) {
    const fresh = await Trustware.buildRoute(request);
    showRouteForReview(fresh);
    return;
  }
  throw error;
}

Trustware.buildRoute() and Trustware.buildDepositAddress() throw RouteResponseError when a route response has no valid expiresAt or Date header. Its field says which. See RouteResponseError.

Refused receipts

Trustware.submitReceipt() throws ReceiptCommitError when Trustware refuses the commit. Branch on error.retryable or error.code, never on the message. retryable is true only for the codes that mean “retry shortly”, so a code your SDK version doesn’t know is final. Requires SDK 1.1.18 or later.

import { ReceiptCommitError, Trustware } from "@trustware/sdk";

function shouldRetry(error: unknown): boolean {
  if (error instanceof ReceiptCommitError) return error.retryable;
  // A 5xx carries no refusal code. It is an Error named "HttpError".
  return (
    error instanceof Error &&
    error.name === "HttpError" &&
    "status" in error &&
    typeof error.status === "number" &&
    error.status >= 500
  );
}

async function commit(intentId: string, txHash: string) {
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      return await Trustware.submitReceipt(intentId, txHash);
    } catch (error) {
      if (!shouldRetry(error)) throw error;
      await new Promise((resolve) => setTimeout(resolve, 2000));
    }
  }
  throw new Error(`Receipt for ${intentId} still not accepted after 5 attempts`);
}

Retrying the same commit is safe; see retries. Refusal codes lists every code.

A resolved poll is not a success

Trustware.pollStatus() resolves when the route reaches success, failed, or expired, and when polling times out. A timeout resolves with the last status it saw, which can be pending, submitted, bridging, or a value newer than your SDK version. Always branch on the status. Polling stops at expired from SDK 1.1.18. Earlier versions keep polling an expired intent until the timeout.

const result = await Trustware.pollStatus(route.intentId);

if (result.status !== "success") {
  showIncomplete(route.intentId, result.status);
  return;
}

Polling an intent that has no receipt yet

Before a receipt is submitted, status resolves with "pending", a stub with no transaction fields, so check status before reading sourceTxHash, toAmountWei, or any other transaction field. pollStatus keeps polling through it. A 404 is different. It means the intent ID is unknown, so the SDK throws out of the poll loop rather than retrying to the timeout. Catch it as a terminal failure. The SDK throws it as an Error named "HttpError" with a numeric status. HttpError is not exported, so check name and status rather than the message.

try {
  const result = await Trustware.pollStatus(route.intentId);

  if (result.status === "pending") {
    // Polling timed out before the receipt landed.
    showStillWaiting(route.intentId);
    return;
  }
} catch (error) {
  if (
    error instanceof Error &&
    error.name === "HttpError" &&
    "status" in error &&
    error.status === 404
  ) {
    // Unknown intent ID: stop tracking it.
    showUnrecoverable(error);
    return;
  }
  throw error;
}

The `RouteError` class

When the routing API cannot produce a route, Trustware.buildRoute() and Trustware.buildDepositAddress() throw a RouteError. It extends the native Error class directly (not TrustwareError), so an instanceof TrustwareError check will not match it. message is the API’s one-line summary, as in earlier versions. Requires SDK 1.1.15 or later; through 1.1.13 these methods throw a plain Error.

Field	Description
`status`	The HTTP status, or `0` when the SDK refused the route itself.
`code`	The verdict, or `""` when the API sent none.
`providers`	Per-provider results, each with `name`, `outcome`, `code`, and `message`.
`providerCodes`	The distinct `code` values across `providers`.
`isNoRouteAvailable`	`true` when `code` is `no_route_available` or `status` is `404`, so on its own it does not prove every provider declined.
`isInvalidAddress`	`true` when `code` is `invalid_address`. Requires SDK 1.1.16 or later.

status, code, and the provider codes match the endpoint’s error responses. buildRoute() rejects a malformed address itself with a plain Error, so invalid_address covers what only the API can check, such as a wrong EVM checksum.

Routes whose fees exceed their output

buildRoute() and buildDepositAddress() refuse a route whose fees exceed what it delivers, and sendRouteTransaction() refuses one before the wallet is asked to sign. The RouteError has status 0 and code "fees_exceed_output", with one provider entry carrying the same code. The API runs a similar check and reports a losing route as a fees_exceed_output decline, so branch on the provider code to handle both.

import { isRouteError, RouteDeclineCode, Trustware } from "@trustware/sdk";

try {
  const route = await Trustware.buildRoute({ /* ... */ });
} catch (error) {
  if (isRouteError(error)) {
    if (error.isInvalidAddress) {
      showAddressError(error.message);
      return;
    }
    if (error.providerCodes.includes(RouteDeclineCode.FeesExceedOutput)) {
      showFeesTooHigh();
      return;
    }
    if (error.providerCodes.includes(RouteDeclineCode.AmountTooLow)) {
      askForLargerAmount(error.providers);
      return;
    }
    if (error.isNoRouteAvailable) {
      suggestDifferentToken();
      return;
    }
    retryShortly(); // a provider failed; the pair may still route
    return;
  }
  throw error;
}

isRouteError() also recognizes a RouteError thrown by another copy of the SDK bundle, so prefer it over instanceof. parseRouteError(value) returns the same facts, plus the minimum amount a provider asked for when one did, or null when the value carries no routing verdict. formatMinimum(minimum) renders that minimum for display.

The `RateLimitError` class

When your integration hits the API rate limit, the SDK surfaces the 429 as a RateLimitError. It extends the native Error class directly (not TrustwareError), so a single instanceof TrustwareError check will not match it; handle it as a separate case. The SDK has already waited out the limit on the server’s own schedule before throwing, so do not retry straight away. retriesExhausted says which case you are in: false means the wait is known and longer than the SDK will block for, so rateLimitInfo.retryAfter tells the user when to come back; true means the response carried no usable timing at all.

import { RateLimitError, Trustware } from "@trustware/sdk";

try {
  await Trustware.runTopUp({ fromAmount: "1000000" });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Rate limited; decide how your app should respond.
  }
}

Rate limiting and retry configuration covers the retry behavior, the two retriesExhausted cases, and the monitoring callbacks. The rateLimitInfo property has the following shape:

Field	Type	Description
`limit`	`number`	Maximum requests allowed in the current window
`remaining`	`number`	Requests remaining in the current window
`reset`	`number`	Unix timestamp when the rate limit window resets
`retryAfter`	`number \| undefined`	Seconds until the limit resets (only present on 429 responses)

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Handle errors from the Trustware SDK

The `TrustwareError` class

Error codes

Handling errors via `onError`

Handling errors with try/catch

Errors that are not `TrustwareError`

Destination posthook validation

Source token approvals

Route approvals with no usable amount

Expired routes

Refused receipts

A resolved poll is not a success

Polling an intent that has no receipt yet

The `RouteError` class

Routes whose fees exceed their output

The `RateLimitError` class

The TrustwareError class

Error codes

Handling errors via onError

Handling errors with try/catch

Errors that are not TrustwareError

Destination posthook validation

Source token approvals

Route approvals with no usable amount

Expired routes

Refused receipts

A resolved poll is not a success

Polling an intent that has no receipt yet

The RouteError class

Routes whose fees exceed their output

The RateLimitError class

The `TrustwareError` class

Handling errors via `onError`

Errors that are not `TrustwareError`

The `RouteError` class

The `RateLimitError` class