Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trustware.io/llms.txt

Use this file to discover all available pages before exploring further.

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, or imperatively by catching thrown errors in the headless core.

​
The TrustwareError class

TrustwareError extends the native Error class with three additional fields:
FieldTypeDescription
codeTrustwareErrorCodeMachine-readable error code — use this for branching logic
messagestringTechnical description of the error
userMessagestring | undefinedOptional human-readable message suitable for display
causeunknown | undefinedThe 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.
CodeTypical cause
INVALID_CONFIGThe configuration object is missing required fields or has an invalid value
INVALID_API_KEYThe API key was rejected — thrown during Trustware.init()
WALLET_NOT_CONNECTEDA wallet operation was attempted before a wallet was connected
BRIDGE_FAILEDThe cross-chain bridge transaction could not be completed
NETWORK_ERRORA network request failed (timeout, DNS failure, or server error)
INPUT_ERRORThe input to a core method (amount, address, etc.) is invalid
UNKNOWN_ERRORAn 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 throws 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) {
    console.error("Rate limited", error.rateLimitInfo);
  }
}
The rateLimitInfo property has the following shape:
FieldTypeDescription
limitnumberMaximum requests allowed in the current window
remainingnumberRequests remaining in the current window
resetnumberUnix timestamp when the rate limit window resets
retryAfternumber | undefinedSeconds until the limit resets (only present on 429 responses)
By default, the SDK automatically retries rate-limited requests with exponential backoff up to 3 times. RateLimitError is only thrown when all retries are exhausted. You can configure this behavior via the retry option in TrustwareConfigOptions.