Handle errors from the Trustware SDK

The Trustware SDK surfaces errors through a typed TrustwareError class, so you always know what went wrong and why. 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 covers all error conditions the SDK can produce.

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);
    }
  }
}

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.

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

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)

Documentation Index

​The TrustwareError class

​Error codes

​Handling errors via onError

​Handling errors with try/catch

​The RateLimitError class

The `TrustwareError` class

Error codes

Handling errors via `onError`

Handling errors with try/catch

The `RateLimitError` class