Error Handling

Handle SDK errors with structured error codes and recovery patterns

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 '@testinprod-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, indexerUrl, 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, { 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, { 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

1. Match on error.code, not error.message. Codes are stable across versions; messages may change.

2. Never show raw error messages to users. Map codes to context-appropriate messages.

3. Handle TRANSACTION_REJECTED silently. The user intentionally cancelled.

4. Use error.retryable for retry logic. The SDK marks transient errors as retryable.

5. 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.