SDK Error Reference

The Veil SDK and the underlying Soroban wallet contract produce typed errors. This page enumerates every error class and contract error code, when each is thrown, and how to recover.

TypeScript SDK errors

These classes are thrown by methods in invisible-wallet-sdk. They extend the native Error class, so you can catch them with a standard try/catch and narrow by instanceof or by the .name property.

NoGuardianSet

When thrown: You called initiateRecovery() or completeRecovery() on a wallet that was never configured with a guardian key via setGuardian().

Recovery: Register a guardian before initiating recovery. If you are already locked out and no guardian was ever set, there is no programmatic recovery path — the wallet contract is inaccessible.

import { NoGuardianSet } from 'invisible-wallet-sdk'
 
try {
  await wallet.initiateRecovery(guardianKeypair)
} catch (err) {
  if (err instanceof NoGuardianSet) {
    // prompt user to set a guardian before this flow is reachable
  }
}

RecoveryTimelockActive

When thrown: You called completeRecovery() before the on-chain timelock has expired. The expiresAt Unix timestamp (seconds) is the earliest time the recovery can be completed.

Recovery: Wait until expiresAt and retry. Display the expiry time to the user so they know when to return.

import { RecoveryTimelockActive } from 'invisible-wallet-sdk'
 
try {
  await wallet.completeRecovery(newPublicKey, guardianKeypair)
} catch (err) {
  if (err instanceof RecoveryTimelockActive) {
    const unlockDate = new Date(err.message.split('until ')[1])
    console.log(`Try again after ${unlockDate.toLocaleString()}`)
  }
}

RecoveryNotPending

When thrown: You called completeRecovery() but no recovery was ever initiated for this wallet, or a previous recovery was already completed or cancelled.

Recovery: Call initiateRecovery() first to start a new recovery window, then wait for the timelock to expire before calling completeRecovery().

Contract error codes (WalletError)

The WalletError enum is defined in contracts/invisible_wallet/src/lib.rs. When a Soroban invocation fails with one of these codes the SDK wraps it in a standard Error whose message contains the numeric code returned by the RPC node.

Mapping contract codes to SDK errors

When the Soroban RPC returns a simulation or transaction failure the error object contains a diagnosticEvents array. The contract code is embedded as a u32 in the event data. The SDK does not currently re-wrap these into typed classes; callers must inspect the raw RPC error. A future SDK release will expose a helper:

// Planned (not yet released)
import { parseContractError } from 'invisible-wallet-sdk'
 
try {
  await wallet.send(destination, amount, signerKeypair)
} catch (err) {
  const code = parseContractError(err) // returns WalletError code or null
  if (code === 6) { /* SignatureVerificationFailed — re-request assertion */ }
}