Errors

@bsv/simple provides a hierarchy of error classes for domain-specific error handling. All errors extend the base SimpleError.

Source: src/core/errors.ts

Error Hierarchy

SimpleError (base)
├── WalletError
├── TransactionError
├── MessageBoxError
├── CertificationError
├── DIDError
└── CredentialError

SimpleError

Base class for all library errors.

class SimpleError extends Error {
  code?: string
  constructor(message: string, code?: string)
}

Property	Type	Description
message	string	Human-readable error description
code	string?	Machine-readable error code
name	string	'SimpleError'

WalletError

Wallet initialization and connection errors.

class WalletError extends SimpleError {
  constructor(message: string)
}

Property	Value
name	'WalletError'
code	'WALLET_ERROR'

Example triggers:

• Failed to connect to wallet extension

• Invalid identity key

• Client not available

TransactionError

Transaction creation and signing errors.

class TransactionError extends SimpleError {
  constructor(message: string)
}

Property	Value
name	'TransactionError'
code	'TRANSACTION_ERROR'

Example triggers:

• createAction() fails

• signAction() fails

• Output parsing errors

MessageBoxError

MessageBox P2P messaging errors.

class MessageBoxError extends SimpleError {
  constructor(message: string)
}

Property	Value
name	'MessageBoxError'
code	'MESSAGEBOX_ERROR'

Example triggers:

• Failed to anoint MessageBox host

• Payment send/receive failures

• Identity registry communication errors

CertificationError

Certificate issuance and management errors.

class CertificationError extends SimpleError {
  constructor(message: string)
}

Property	Value
name	'CertificationError'
code	'CERTIFICATION_ERROR'

Example triggers:

• Certificate issuance fails

• Certificate acquisition from remote server fails

• Relinquish fails

DIDError

DID parsing and registration errors.

class DIDError extends SimpleError {
  constructor(message: string)
}

Property	Value
name	'DIDError'
code	'DID_ERROR'

Example triggers:

• Invalid DID format (not did:bsv: prefix)

• Invalid identity key in DID string

• DID registration failure

CredentialError

Verifiable Credential errors.

class CredentialError extends SimpleError {
  constructor(message: string)
}

Property	Value
name	'CredentialError'
code	'CREDENTIAL_ERROR'

Example triggers:

• Unknown schema ID

• Field validation failure

• Revocation enabled but no wallet provided

• Revocation UTXO creation failure

• Certificate already revoked

Catching Errors

import { SimpleError, WalletError, CredentialError } from '@bsv/simple/browser'

try {
  await wallet.pay({ to: key, satoshis: 1000 })
} catch (error) {
  if (error instanceof WalletError) {
    console.error('Wallet issue:', error.message)
  } else if (error instanceof SimpleError) {
    console.error(`${error.code}: ${error.message}`)
  } else {
    console.error('Unexpected:', error)
  }
}

Note on Module Errors

Many module methods (tokens, inscriptions, messagebox, overlay) wrap errors in plain Error instances with descriptive prefixes rather than using the typed error classes:

throw new Error(`Token creation failed: ${originalError.message}`)
throw new Error(`Payment failed: ${originalError.message}`)

The typed error classes (DIDError, CredentialError) are used primarily by the DID and credentials modules. You can catch these specifically or catch the generic Error type for other modules.