Documentation Index
Fetch the complete documentation index at: https://docs.privacyboost.io/llms.txt
Use this file to discover all available pages before exploring further.
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);
}
}
}
}
| 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, { 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
-
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
React Native
React Native SDK
For deeper TypeScript error handling patterns (retry logic, WASM loading, caching), see the TypeScript Error Handling guide.