Error Handling

This guide covers error types and handling strategies in the Privacy Boost TypeScript SDK.

Error Types

All SDK errors extend from PrivacyBoostError:

class PrivacyBoostError extends Error {
  code: string;          // Error code for programmatic handling
  message: string;       // Human-readable message
  retryable: boolean;    // Whether the operation can be retried
  cause?: Error;         // Original error if wrapped

  isAuthError(): boolean;     // Check if this is an auth-related error
  isWalletError(): boolean;   // Check if this is a wallet-related error
  hasCode(): boolean;         // Check if a specific error code is set
  static from(error: unknown): PrivacyBoostError; // Wrap unknown errors
}

Error Categories

Configuration Errors

Code	Description
`INVALID_CONFIG`	Invalid SDK configuration

try {
  await PrivacyBoost.create({
    serverUrl: 'invalid-url', // Will throw
    // ...
  });
} catch (error) {
  if (error.code === 'INVALID_CONFIG') {
    console.log('Please provide valid configuration');
  }
}

Wallet Errors

Code	Description
`TRANSACTION_REJECTED`	User rejected the request
`WRONG_NETWORK`	Wrong network

try {
  await sdk.auth.authenticate(adapter);
} catch (error) {
  switch (error.code) {
    case 'TRANSACTION_REJECTED':
      showToast('Authentication cancelled');
      break;
    case 'WRONG_NETWORK':
      showToast('Please switch to the correct network');
      break;
    default:
      showToast('Authentication failed');
  }
}

Authentication Errors

Code	Description
`NOT_AUTHENTICATED`	Not authenticated
`AUTH_NONCE_EXPIRED`	Authentication nonce expired
`AUTH_INVALID_SIGNATURE`	Invalid signature
`SESSION_EXPIRED`	JWT token expired

try {
  await sdk.auth.authenticate(adapter);
} catch (error) {
  if (error.code === 'AUTH_NONCE_EXPIRED') {
    // Retry authentication
    await sdk.auth.authenticate(adapter);
  }
}

Operation Errors

Code	Description
`TRANSFER_PROOF_FAILED`	Transfer proof generation failed

try {
  await sdk.vault.shield(params);
} catch (error) {
  switch (error.code) {
    case 'TRANSACTION_REJECTED':
      showError('Transaction cancelled');
      break;
    case 'TRANSFER_PROOF_FAILED':
      showError('Proof generation failed');
      break;
    default:
      showError('Deposit failed: ' + error.message);
  }
}

Network Errors

Code	Description
`TIMEOUT`	Request timed out
`HTTP_ERROR`	HTTP request failed
`RATE_LIMITED`	Rate limited

try {
  await sdk.vault.getBalance(tokenAddress);
} catch (error) {
  if (error.code === 'TIMEOUT') {
    // Retry after delay
    await delay(2000);
    await sdk.vault.getBalance(tokenAddress);
  }
}

Proof Errors

Code	Description
`TRANSFER_PROOF_FAILED`	Failed to generate transfer proof

Error Handling Patterns

Basic Try-Catch

try {
  await sdk.vault.shield(params);
} catch (error) {
  if (error instanceof PrivacyBoostError) {
    console.log('SDK Error:', error.code, error.message);
  } else {
    console.log('Unknown error:', error);
  }
}

Error Handler Function

function handleError(error: unknown): string {
  if (!(error instanceof PrivacyBoostError)) {
    return 'An unexpected error occurred';
  }

  const messages: Record<string, string> = {
    TRANSACTION_REJECTED: 'Request cancelled',
    SESSION_EXPIRED: 'Session expired, please login again',
    TIMEOUT: 'Request timed out, please try again',
    WRONG_NETWORK: 'Please switch to the correct network',
  };

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

// Usage
try {
  await sdk.vault.transfer(params);
} catch (error) {
  showToast(handleError(error));
}

Retry Logic

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  delay = 1000
): Promise<T> {
  let lastError: Error;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;

      // Don't retry user rejections
      if (error.code === 'TRANSACTION_REJECTED') {
        throw error;
      }

      // Retry retryable errors
      if (error.retryable) {
        await new Promise((r) => setTimeout(r, delay * attempt));
        continue;
      }

      throw error;
    }
  }

  throw lastError!;
}

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

Session Refresh

async function withSessionRefresh<T>(
  operation: () => Promise<T>
): Promise<T> {
  try {
    return await operation();
  } catch (error) {
    if (error.code === 'SESSION_EXPIRED') {
      await sdk.auth.authenticate(adapter);
      return await operation();
    }
    throw error;
  }
}

// Usage
const history = await withSessionRefresh(() =>
  sdk.transactions.fetchHistory()
);

React Error Boundary

class PrivacyBoostErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { error: Error | null }
> {
  state = { error: null };

  static getDerivedStateFromError(error: Error) {
    return { error };
  }

  render() {
    if (this.state.error) {
      return (
        <div>
          <h2>Something went wrong</h2>
          <p>{this.state.error.message}</p>
          <button onClick={() => this.setState({ error: null })}>
            Try again
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

React Hook for Error Handling

function useSDKOperation<T>(operation: () => Promise<T>) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<PrivacyBoostError | null>(null);
  const [data, setData] = useState<T | null>(null);

  const execute = useCallback(async () => {
    setLoading(true);
    setError(null);

    try {
      const result = await operation();
      setData(result);
      return result;
    } catch (err) {
      const sdkError = err instanceof PrivacyBoostError ? err : PrivacyBoostError.from(err);
      setError(sdkError);
      throw sdkError;
    } finally {
      setLoading(false);
    }
  }, [operation]);

  return { execute, loading, error, data };
}

// Usage
function ShieldButton({ tokenAddress, amount }: { tokenAddress: Hex; amount: bigint }) {
  const { execute, loading, error } = useSDKOperation(() =>
    sdk.vault.shield({ tokenAddress, amount })
  );

  return (
    <>
      <button onClick={execute} disabled={loading}>
        {loading ? 'Processing...' : 'Deposit'}
      </button>
      {error && <p className="error">{error.message}</p>}
    </>
  );
}

Logging Errors

function logError(error: unknown, context: string) {
  if (error instanceof PrivacyBoostError) {
    console.error(`[${context}] SDK Error:`, {
      code: error.code,
      message: error.message,
      cause: error.cause,
    });
  } else {
    console.error(`[${context}] Unknown error:`, error);
  }
}

// Usage
try {
  await sdk.vault.shield(params);
} catch (error) {
  logError(error, 'deposit');
  throw error;
}

Best Practices

1. Always Handle User Rejections Gracefully

if (error.code === 'TRANSACTION_REJECTED') {
  // Don't show error, user intentionally cancelled
  return;
}

2. Provide Actionable Error Messages

const actionableMessages: Record<string, string> = {
  WRONG_NETWORK: 'Click here to switch networks',
  SESSION_EXPIRED: 'Click to reconnect your wallet',
  TRANSACTION_REJECTED: 'Transaction was cancelled',
};

3. Log Errors for Debugging

catch (error) {
  // Log for developers
  console.error('Operation failed:', error);

  // Show user-friendly message
  showToast(getUserMessage(error));
}

4. Use Error Codes, Not Messages

// BAD - Message might change
if (error.message.includes('rejected')) {
  // ...
}

// GOOD - Code is stable
if (error.code === 'TRANSACTION_REJECTED') {
  // ...
}

Next Steps

Performance

Quickstart

Setup

SDKs

Error handling

Error Handling

Error Types

Error Categories

Configuration Errors

Wallet Errors

Authentication Errors

Operation Errors

Network Errors

Proof Errors

Error Handling Patterns

Basic Try-Catch

Error Handler Function

Retry Logic

Session Refresh

React Error Boundary

React Hook for Error Handling

Logging Errors

Best Practices

1. Always Handle User Rejections Gracefully

2. Provide Actionable Error Messages

3. Log Errors for Debugging

4. Use Error Codes, Not Messages

Next Steps

​Error Handling

​Error Types

​Error Categories

​Configuration Errors

​Wallet Errors

​Authentication Errors

​Operation Errors

​Network Errors

​Proof Errors

​Error Handling Patterns

​Basic Try-Catch

​Error Handler Function

​Retry Logic

​Session Refresh

​React Error Boundary

​React Hook for Error Handling

​Logging Errors

​Best Practices

​1. Always Handle User Rejections Gracefully

​2. Provide Actionable Error Messages

​3. Log Errors for Debugging

​4. Use Error Codes, Not Messages

​Next Steps

Error Handling

Error Types

Error Categories

Configuration Errors

Wallet Errors

Authentication Errors

Operation Errors

Network Errors

Proof Errors

Error Handling Patterns

Basic Try-Catch

Error Handler Function

Retry Logic

Session Refresh

React Error Boundary

React Hook for Error Handling

Logging Errors

Best Practices

1. Always Handle User Rejections Gracefully

2. Provide Actionable Error Messages

3. Log Errors for Debugging

4. Use Error Codes, Not Messages

Next Steps