Error Handling Guide

Error Class Hierarchy

Import

import { OpenloopError, ApduError, TransportError } from '@openloop/sdk-core'
import type { TransportErrorCode } from '@openloop/sdk-core'

// Errors from the Bitcoin module (subpath)
import { BtcError } from '@openloop/sdk-core/bitcoin'
import type { BtcErrorCode } from '@openloop/sdk-core/bitcoin'

BtcError and BtcErrorCode are not exported from the root of @openloop/sdk-core. Import them from @openloop/sdk-core/bitcoin.

You can recognise a BtcError with instanceof. @openloop/sdk-core and @openloop/sdk-core/bitcoin share a single definition of BtcError (and of OpenloopError). A BtcError thrown by BitcoinApp — for example from signPsbt — and one thrown by a subpath function both match instanceof against the BtcError you imported from the subpath, and both match instanceof OpenloopError (0.8.1 and later; on 0.8.0 and earlier they do not match, so check name === 'BtcError' and read code instead). Branch on code (see the example under Recognising and handling a BtcError). ApduError and TransportError can also be told apart with instanceof, because every transport package shares @openloop/sdk-core.

Which Error Arrives On Which Path

With LocalWS, the JSON-RPC error returned by Connect is placed in the TransportError message as RPC error: <Connect's text> (<JSON-RPC code>). The status word does not arrive in structured form, so you cannot branch on statusWord. With WalletConnect, WcTransport does not wrap exceptions.

ApduError

Thrown when the device returns an error status word — anything other than 0x9000 and 0x61XX.

class ApduError extends OpenloopError {
  readonly statusWord: number  // e.g. 0x6985
}

message has the form APDU error: 0x6985 (User rejected on device) — the status word as four hex digits, then the English description from the table below in parentheses. A status word that is not in the table gets (Unknown error).

APDU Status Word Table

Example

import { ApduError, DEFAULT_ETH_PATH } from '@openloop/sdk-core'

try {
  const sig = await eth.signPersonalMessage(DEFAULT_ETH_PATH, 'Hello')
} catch (err) {
  if (err instanceof ApduError) {
    if (err.statusWord === 0x6985) {
      console.log('Rejected on the device, or the device is busy. Check the screen and try again')
    } else {
      console.log(`APDU error: 0x${err.statusWord.toString(16)}`)
    }
  }
}

USB HID (Node.js) Note

@openloop/transport-usb turns only these status words into an ApduError: 0x6700, 0x6982, 0x6985, 0x6d00, 0x6e00, 0x6f00, the 0x6aXX family, and 0x61XX (more data). Anything else (for example 0x6983, 0x6984 or 0x6986) is treated as a corrupted response: the transport reopens the connection and retries (3 attempts by default, adjustable with the maxRetries option), then fails with a TransportError (code: 'io', message of the form Exchange failed after 3 attempts: ...). An ApduError is never retried.

TransportError

Thrown when a communication error occurs in the transport layer — USB, BLE, WebSocket, and so on.

class TransportError extends OpenloopError {
  readonly code: TransportErrorCode   // added in v0.6.0
  // message carries English detail — for logs, not for display

  // Fields the Safari Extension transport adds from the bridge (all may be absent)
  stale?: boolean
  busy?: boolean
  noResponse?: boolean
  sent?: number
  awaited?: boolean
}

Branch on code (added in v0.6.0)

message is free-form English, so do not branch on the string. Branch on code.

code defaults to io. Handle unknown values in a default branch so new codes cannot break you.

A timeout or disconnected during a signing request does not tell you whether the device processed it. Not receiving a response does not prove the request never arrived. Do not resend a call that signs or asks for approval automatically after these errors. Have the user check the device screen, and make the request again only on their action.

Notes Per Transport

• USB HID (Node.js): a failed open() is always code: 'io', including when no device is found (Failed to open HID device: ...). A failed exchange() reopens the connection and retries, and finally fails with code: 'io' (it does not arrive as timeout or disconnected).
• Web Bluetooth: when the chooser is dismissed, WebBleTransport.connect() throws the browser’s exception (a DOMException whose name is NotFoundError) as is, not a TransportError. If you do not want a dismissed chooser to count as a failure, use WebBleTransport.pick() first — it returns null when the chooser is dismissed.
• BLE (Web Bluetooth / Node.js): when the device reports, by notification, an input that failed its frame check, the exchange ends on the spot with code: 'io'.
• LocalWS: open() fails with timeout after 5 seconds, or not-connected on a connection error. An RPC timeout is timeout, and a dropped connection is disconnected.
• WalletConnect (WcTransport): calling exchange() / lock() / unlock() before connecting gives not-connected.

Errors the device returned are ApduError

In v0.6.0 the BLE, Safari and USB transports stopped discarding the status word and now throw ApduError. Previously these surfaced as TransportError, so callers could not branch on statusWord. Handle device-side failures (rejection, conditions not satisfied, and so on) in the ApduError branch. LocalWS and WalletConnect are the exceptions — they do not produce an ApduError (Which Error Arrives On Which Path).

Fields Added By the Safari Extension

The Safari Extension transport (@openloop/transport-safari) copies the bridge’s notice onto the TransportError. Every field may be absent, so never read a missing field as “safe”. Other transports do not set them.

The Safari transport resends once, and only when sent === 0 and awaited is not true. In every other case it does not resend.

BtcError

The error thrown by @openloop/sdk-core/bitcoin (the Bitcoin module). code is the key for your own translation table; message is English and meant for logs (the SDK carries no on-screen text).

class BtcError extends OpenloopError {
  readonly code: BtcErrorCode
}

type BtcErrorCode =
  | 'bad_argument'
  | 'invalid_address'
  | 'network_mismatch'
  | 'fetch_failed'
  | 'bad_response'
  | 'prev_tx_too_large'
  | 'fee_rate_out_of_range'
  | 'insufficient'
  | 'insufficient_unconfirmed'
  | 'fee_too_high'
  | 'fee_exceeds_amount'
  | 'psbt_too_large'
  | 'bad_psbt'
  | 'broadcast_rejected'

Code Reference

The endpoints, timeouts, paths and network are all passed in by the caller. The SDK carries no defaults and keeps no state.

Errors That Are Not BtcError

• Among the public Bitcoin functions, the encoding and derivation building blocks (decodeExtendedPubkey, base58CheckDecode, deriveChildPublicKey, encodeSegwitAddress, decodeSegwitAddress) throw a plain Error, not a BtcError.
• Parsing of BitcoinApp responses (a depth or version mismatch in an extended public key, a response of the wrong length, and so on) also throws a plain Error.
• EthereumApp throws a plain Error if you call EIP-712 streaming or EIP-7702 signing on a Ledger-compatible device. signTypedDataStreaming throws a plain Error when a type or value cannot be encoded.

These are not OpenloopErrors, so they fall into the final else (rethrow) of the basic pattern.

Recognising and Handling a BtcError

import { BtcError, type BtcErrorCode } from '@openloop/sdk-core/bitcoin'

/** Returns the code if err is a BtcError */
function btcCode(err: unknown): BtcErrorCode | null {
  return err instanceof BtcError ? err.code : null
}

function describeBtcError(err: unknown): string | null {
  switch (btcCode(err)) {
    case null:
      return null // not a BtcError
    case 'invalid_address':
      return 'The address is not valid'
    case 'network_mismatch':
      return 'This address is for another network'
    case 'insufficient':
      return 'Insufficient balance'
    case 'insufficient_unconfirmed':
      return 'Some incoming funds are unconfirmed. You can send once they confirm'
    case 'fee_too_high':
    case 'fee_exceeds_amount':
    case 'fee_rate_out_of_range':
      return 'The fee looks abnormal. The payment was stopped'
    case 'fetch_failed':
      return 'Could not check the balance. Please try again'
    case 'broadcast_rejected':
      return 'Could not send the transaction. Please check its status'
    default:
      return 'The operation failed' // bad_argument and others — details go to the log
  }
}

Error Handling Patterns

The Basic Pattern

import { OpenloopError, ApduError, TransportError, DEFAULT_ETH_PATH } from '@openloop/sdk-core'

try {
  const { address } = await eth.getAddress(DEFAULT_ETH_PATH)
} catch (err) {
  if (err instanceof ApduError) {
    // Error response from the device
    switch (err.statusWord) {
      case 0x6985:
        showMessage('Rejected on the device, or the device is busy. Check the screen and try again')
        break
      case 0x6a80:
        showMessage('Invalid data')
        break
      default:
        showMessage(`Device error: ${err.message}`)
    }
  } else if (err instanceof TransportError) {
    // Communication error — branch on code, not on message
    switch (err.code) {
      case 'not-supported':
        showMessage('This browser is not supported.')
        break
      case 'not-found':
        showMessage('No device was found.')
        break
      case 'timeout':
        showMessage('The device is not responding. Please check its screen.')
        break
      case 'disconnected':
      case 'not-connected':
        showMessage('Lost the connection to the device. Please reconnect.')
        break
      default:
        showMessage(`Communication error: ${err.message}`)
    }
  } else if (err instanceof OpenloopError) {
    // Any other SDK error
    showMessage(`Error: ${err.message}`)
  } else {
    // Unexpected error (a BtcError, a plain Error, and so on)
    throw err
  }
}

Retry Pattern With Reconnect

Use this only for calls that do not change the device’s state (such as fetching an address). A call that signs or asks for approval must not be resent automatically: after a timeout or disconnected, the device may already have acted on it.

import { EthereumApp, DEFAULT_ETH_PATH, TransportError } from '@openloop/sdk-core'
import { WebHidTransport } from '@openloop/transport-webhid'

async function withRetry<T>(
  fn: () => Promise<T>,
  reconnect: () => Promise<void>,
  maxRetries: number = 1
): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      return await fn()
    } catch (err) {
      if (err instanceof TransportError && i < maxRetries) {
        await reconnect()
        continue
      }
      throw err
    }
  }
  throw new Error('Unreachable')
}

// Usage example
let transport = await WebHidTransport.connect()
let eth = new EthereumApp(transport)

const { address } = await withRetry(
  () => eth.getAddress(DEFAULT_ETH_PATH),
  async () => {
    const t = await WebHidTransport.reconnect()
    if (!t) throw new Error('Device not found')
    transport = t
    eth = new EthereumApp(transport)
  }
)

Detecting a Rejection or a Busy Device

import { ApduError, DEFAULT_ETH_PATH } from '@openloop/sdk-core'

function isRejectedOrBusy(err: unknown): boolean {
  return err instanceof ApduError && err.statusWord === 0x6985
}

async function signAndHandle(): Promise<void> {
  try {
    const sig = await eth.signTransaction(DEFAULT_ETH_PATH, rawTx)
    console.log(sig)
  } catch (err) {
    if (isRejectedOrBusy(err)) {
      // Rejected or busy — check the screen and try again
      showMessage('Rejected on the device, or the device is busy. Check the screen and try again')
      return
    }
    // Show every other error
    showError(err)
  }
}

Next Steps

• API Reference — every type definition