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

Errors that are not `TrustwareError`

Some SDK rejections are thrown as a plain Error with no code property. An instanceof TrustwareError check will not match them and error.code will be undefined, so handle them by message or by name.

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 dynamic landed-balance mode. 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. Three 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`
An approval transaction-status lookup failed	an `Error` whose `name` is `"SDKRPCError"`

All three 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.

A resolved poll is not a success

Trustware.pollStatus() resolves when the route reaches success, when it reaches failed, and when polling times out. Always branch on the status.

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

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

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)

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

A resolved poll is not a success

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

​A resolved poll is not a success

​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

A resolved poll is not a success

The `RateLimitError` class