Error Handling

The Privacy Boost SDK uses structured error codes so you can handle errors programmatically. Every error has a stable code string that won’t change between SDK versions.

Quick Example

import { PrivacyBoostError, ErrorCodes } from '@sunnyside-io/privacy-boost';

try {
  await sdk.vault.shield({ tokenAddress, amount });
} catch (error) {
  if (error instanceof PrivacyBoostError) {
    switch (error.code) {
      case ErrorCodes.TRANSACTION_REJECTED:
        // User cancelled — do nothing
        return;
      case ErrorCodes.INSUFFICIENT_BALANCE:
        showToast('Not enough balance');
        return;
      default:
        if (error.retryable) {
          // Network issue — retry after a moment
          await retryLater();
        } else {
          showError(error.message);
        }
    }
  }
}

Error Types by Platform

Platform	Error Type	How to check the code
TypeScript	`PrivacyBoostError`	`error.code`, `error.retryable`, `error.isAuthError()`
iOS (Swift)	`SDKError`	`catch SDKError.networkError(let msg) { ... }`
Android (Kotlin)	`SDKError`	`catch (e: SDKError.NetworkError) { ... }`

TypeScript: PrivacyBoostError

class PrivacyBoostError extends Error {
  code: string;          // e.g. 'WALLET_NOT_CONNECTED'
  message: string;       // Human-readable description
  cause?: Error;         // Original error if wrapped
  retryable: boolean;    // Can this operation be retried?

  isAuthError(): boolean;  // Is this an auth/session error?
  isWalletError(): boolean; // Is this a wallet error?
}

Error Codes

Wallet Errors

These occur when interacting with the user’s wallet.

Code	What happened	User action
`WALLET_NOT_CONNECTED`	No wallet connected	Show “Connect Wallet” button
`WALLET_CONNECTION_FAILED`	Wallet refused or failed to connect	Retry or try a different wallet
`WRONG_NETWORK`	Wallet is on the wrong chain	Show “Switch Network” prompt
`TRANSACTION_REJECTED`	User rejected a signature or transaction	Do nothing (intentional)
`TRANSACTION_FAILED`	On-chain transaction failed	Show error, check gas/params
`INSUFFICIENT_GAS`	Not enough gas for the transaction	Prompt user to add funds

Authentication Errors

These occur during login or when a session expires.

Code	What happened	User action
`NOT_AUTHENTICATED`	Tried to use SDK before logging in	Call `authenticate()` first
`SESSION_EXPIRED`	JWT expired	Re-authenticate (can be automatic)
`AUTHENTICATION_FAILED`	Login failed	Retry or check configuration

Network Errors

These are transient and usually retryable.

Code	What happened	Retryable?
`NETWORK_ERROR`	Connection failed (DNS, timeout, refused)	Yes
`TIMEOUT`	Request took too long	Yes
`RATE_LIMITED`	Too many requests (429)	Yes (with backoff)
`SERVICE_UNAVAILABLE`	Backend is temporarily down	Yes (with backoff)

Operation Errors

These occur during deposits, transfers, or withdrawals.

Code	What happened	User action
`INSUFFICIENT_BALANCE`	Not enough shielded balance	Show balance and suggest depositing more
`INVALID_ADDRESS`	Malformed Ethereum or privacy address	Prompt user to check the address
`INVALID_AMOUNT`	Amount is zero, negative, or malformed	Validate input before calling the SDK
`INVALID_CONFIG`	SDK configuration is invalid	Check `appId`, `serverUrl`, and other config values

Compliance Errors

These occur when a transaction fails compliance screening.

Code	What happened	User action
`COMPLIANCE_BLOCKED`	Address or transaction blocked by compliance screening	Contact support
`TRANSFER_COMPLIANCE_FAILED`	Transfer failed compliance check	Contact support

Crypto Errors

These indicate failures in the cryptographic layer.

Code	What happened	User action
`CRYPTO_ERROR`	General cryptographic operation failed	Report the issue
`ENCRYPTION_ERROR`	Failed to encrypt data	Retry or re-authenticate
`DECRYPTION_ERROR`	Failed to decrypt data (wrong keys or corrupted)	Re-authenticate or restore keys
`KEY_DERIVATION_ERROR`	Failed to derive privacy keys	Re-authenticate

Shield Errors

These occur during shield (deposit) operations.

Code	What happened	User action
`SHIELD_NOT_FOUND`	Shield request not found on-chain	Check transaction hash
`SHIELD_ALREADY_CLAIMED`	Shield has already been claimed	No action needed
`SHIELD_PROOF_EXPIRED`	Shield proof has expired	Re-initiate the shield
`SHIELD_COMMITMENT_NOT_FOUND`	On-chain commitment not found	Wait for indexer to sync

Transfer Errors

These occur during private transfers.

Code	What happened	User action
`TRANSFER_NOT_FOUND`	Transfer not found	Check request ID
`TRANSFER_PROOF_FAILED`	ZK proof generation or verification failed	Retry the transfer
`TRANSFER_SUBMISSION_FAILED`	Transfer could not be submitted to the server	Retry
`BELOW_MIN_TRANSFER_AMOUNT`	Amount is below minimum transfer threshold	Increase amount

Merkle Tree Errors

These occur during proof construction.

Code	What happened	Retryable?
`MERKLE_LEAF_NOT_FOUND`	Note’s leaf not found in the Merkle tree	Yes (indexer may be syncing)
`MERKLE_PROOF_FAILED`	Failed to construct Merkle proof	Yes
`MERKLE_ROOT_STALE`	Merkle root is outdated	Yes (auto-retried by SDK)

Note Errors

These occur when accessing private notes.

Code	What happened	User action
`NOTE_NOT_FOUND`	Note does not exist	Verify the transaction
`NOTE_ALREADY_SPENT`	Note has already been spent (nullifier exists)	No action — note was used
`NOTE_ACCESS_DENIED`	Cannot decrypt this note (wrong keys)	Verify correct account

Internal Errors

These indicate SDK bugs or unexpected server responses.

Code	What happened	User action
`SERIALIZATION_ERROR`	Failed to serialize/deserialize data	Report the issue
`OPERATION_FAILED`	Generic operation failure	Check the error message for details
`INTERNAL_ERROR`	Unexpected internal error	Report the issue with full error details

Recovery Patterns

Handle user rejections gracefully

When a user cancels a wallet popup, don’t show an error dialog — it’s intentional.

try {
  await sdk.auth.authenticate(adapter, { keySource: { type: 'walletDerived' } });
} catch (error) {
  if (error.code === 'TRANSACTION_REJECTED') {
    return; // User cancelled
  }
  showError(error.message);
}

Retry on network errors

Use error.retryable with exponential backoff:

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (!error.retryable || attempt === maxRetries) throw error;
      await new Promise(r => setTimeout(r, 1000 * attempt));
    }
  }
  throw new Error('Unreachable');
}

const balance = await withRetry(() => sdk.vault.getBalance(token));

Re-authenticate on session expiry

async function withAuth<T>(fn: () => Promise<T>): Promise<T> {
  try {
    return await fn();
  } catch (error) {
    if (error.code === 'SESSION_EXPIRED') {
      await sdk.auth.authenticate(adapter, { keySource: { type: 'walletDerived' } });
      return await fn();
    }
    throw error;
  }
}

Map errors to user-friendly messages

function userMessage(error: PrivacyBoostError): string {
  const messages: Record<string, string> = {
    WALLET_NOT_CONNECTED: 'Please connect your wallet',
    TRANSACTION_REJECTED: 'Request cancelled',
    WRONG_NETWORK: 'Please switch to the correct network',
    SESSION_EXPIRED: 'Session expired, please log in again',
    INSUFFICIENT_BALANCE: 'Not enough balance',
    NETWORK_ERROR: 'Connection failed, please try again',
    RATE_LIMITED: 'Too many requests, please wait',
  };

  return messages[error.code] || error.message;
}

Best Practices

Match on error.code, not error.message. Codes are stable across versions; messages may change.
Never show raw error messages to users. Map codes to context-appropriate messages.
Handle TRANSACTION_REJECTED silently. The user intentionally cancelled.
Use error.retryable for retry logic. The SDK marks transient errors as retryable.
Log the full error internally. Capture code, message, and cause for debugging, even when showing a simple message to the user.

Next Steps

You’ve completed the Setup section. Now dive into your platform SDK:

TypeScript

Full web SDK guide

React

Hooks and components

iOS

Native Swift SDK

Android

Native Kotlin SDK

React Native

React Native SDK

CLI

Command-line tool

For deeper TypeScript error handling patterns (retry logic, WASM loading, caching), see the TypeScript Error Handling guide.

Quickstart

Setup

SDKs

Error Handling

Error Handling

Quick Example

Error Types by Platform

TypeScript: PrivacyBoostError

Error Codes

Wallet Errors

Authentication Errors

Network Errors

Operation Errors

Compliance Errors

Crypto Errors

Shield Errors

Transfer Errors

Merkle Tree Errors

Note Errors

Internal Errors

Recovery Patterns

Handle user rejections gracefully

Retry on network errors

Re-authenticate on session expiry

Map errors to user-friendly messages

Best Practices

Next Steps

TypeScript

React

iOS

Android

React Native

CLI

​Error Handling

​Quick Example

​Error Types by Platform

​TypeScript: PrivacyBoostError

​Error Codes

​Wallet Errors

​Authentication Errors

​Network Errors

​Operation Errors

​Compliance Errors

​Crypto Errors

​Shield Errors

​Transfer Errors

​Merkle Tree Errors

​Note Errors

​Internal Errors

​Recovery Patterns

​Handle user rejections gracefully

​Retry on network errors

​Re-authenticate on session expiry

​Map errors to user-friendly messages

​Best Practices

​Next Steps

TypeScript

React

iOS

Android

React Native

CLI

Error Handling

Quick Example

Error Types by Platform

TypeScript: PrivacyBoostError

Error Codes

Wallet Errors

Authentication Errors

Network Errors

Operation Errors

Compliance Errors

Crypto Errors

Shield Errors

Transfer Errors

Merkle Tree Errors

Note Errors

Internal Errors

Recovery Patterns

Handle user rejections gracefully

Retry on network errors

Re-authenticate on session expiry

Map errors to user-friendly messages

Best Practices

Next Steps