Trustware: What Happens When a Cross-Chain Deposit Route Fails Mid-Transaction

TL;DR: A failed cross-chain deposit shouldn't be a mystery to debug from scratch. Trustware surfaces failures as typed errors, wallet not connected, bridge failed, network error, invalid input, rather than a generic exception, plus a status event stream so your app can respond to the specific failure instead of guessing.

What can actually go wrong during a cross-chain deposit?

A route can fail because a wallet disconnects mid-flow, the underlying bridge step fails, a network request times out or errors, the destination configuration is invalid, or the user's input doesn't meet route constraints, each a distinct failure mode requiring a different response from your app.

How Trustware surfaces these failures

Typed error codes instead of generic exceptions

Errors are raised as a TrustwareError carrying a specific code: INVALID_CONFIG, INVALID_API_KEY, WALLET_NOT_CONNECTED, BRIDGE_FAILED, NETWORK_ERROR, INPUT_ERROR, or a fallback UNKNOWN_ERROR. Each error also carries an optional user-facing message separate from the technical one, so your app can show something appropriate to an end user without exposing internal detail.

An event stream for transaction lifecycle

Beyond thrown errors, the SDK emits lifecycle events: transaction_started, transaction_success with a transaction hash, wallet_connected, and route-specific events like swap_route_changed, giving your app visibility into where in the flow a transaction actually is, not just whether it ultimately succeeded or failed.

Rate limiting as a distinct, handled case

Hitting a rate limit isn't treated as a generic network failure; configurable retry behavior handles it automatically, and if retries are exhausted, a specific RateLimitError is thrown carrying rate-limit details your app can act on.

The Trustware view, error handling is part of the integration, not an edge case to skip

A deposit flow that only handles the success path looks complete in a demo and breaks down the first time a real network hiccup or a disconnected wallet occurs in production. Typed errors and lifecycle events exist specifically so this handling doesn't have to be reverse-engineered from generic stack traces after the fact.

A contrarian take, "the transaction failed" is rarely the useful thing to tell a user

A generic failure message tells a user nothing about whether to retry, reconnect their wallet, or contact support. Distinguishing WALLET_NOT_CONNECTED from BRIDGE_FAILED from NETWORK_ERROR lets your app give a genuinely different, actionable message for each, rather than one unhelpful catch-all.

What to build around this error model

• Are you catching and branching on specific TrustwareErrorCode values, or treating all errors the same?
• Does your UI distinguish a wallet-connection failure from a bridge-execution failure for the user?
• Are you subscribing to lifecycle events to show progress, not just a final success or failure state?
• Have you tested your handling of a RateLimitError specifically, not just a generic network error?
• Does your support process have access to the technical error code, not just whatever message the user saw?

See the Trustware docs for current error handling reference.

FAQ

What error codes does Trustware's SDK expose?

INVALID_CONFIG, INVALID_API_KEY, WALLET_NOT_CONNECTED, BRIDGE_FAILED, NETWORK_ERROR, INPUT_ERROR, and a fallback UNKNOWN_ERROR.

Does every error include a message safe to show end users?

Errors can carry an optional user-facing message separate from the internal technical message, though your app should confirm which errors populate this before relying on it for every case.

What happens if I hit an API rate limit?

Configurable retry behavior handles it automatically; if retries are exhausted, a typed RateLimitError is thrown with rate-limit details.

Can I track transaction progress before it succeeds or fails?

Yes, lifecycle events including transaction_started and wallet_connected give visibility into the flow before a final outcome.

Does a BRIDGE_FAILED error mean my funds are lost?

{{CITE: confirm current fund-safety behavior on BRIDGE_FAILED before publishing; do not assume without verification}}

Should my app log the technical error code or just show the user message?

Both, ideally, the technical code for your own debugging and support process, and the user-facing message for the end user's experience.

How to decide how much error-handling work you need

If your integration currently only handles the success path, prioritize branching on the documented error codes and subscribing to lifecycle events before going to production, since these are exactly the cases most likely to generate support tickets otherwise.

See trustware.io for current documentation.