Error Handling & Performance
This guide covers TypeScript-specific error handling patterns and performance optimization. For the cross-platform error code reference, see Error Handling.PrivacyBoostError
All SDK errors extendPrivacyBoostError:
Type-Safe Error Handling
Retry with Exponential Backoff
Recovering a Lost Submit
A send or unshield whose answer was lost fails withoutcomeUnknown set, and
the payment may still go out. Pass a submissionKey, then look the attempt up
with sdk.transactions.getSubmission(key) before doing anything else. Once the
attempt has arrived it returns its requestId and status, and the tracked
transaction picks the request up and settles like any other. { found: false }
means nothing has arrived under the key yet. Resubmit with the same key only
then: the server answers a duplicate with the first attempt’s request instead
of paying again. Don’t skip the lookup, since a resubmit can be refused before
it’s sent while the first attempt holds its notes.
found: false can also mean the first attempt is still on its way. If it lands
before the resubmit reads your balance, the resubmit is refused before it’s
sent, for example with INSUFFICIENT_BALANCE. A refusal right after
found: false means “look it up again”, not “resubmit under a new key”, which
would pay twice.
unshield you sent with
unwrapWeth, call sdk.vault.unwrapWeth(amount, recipient) once its status is
completed.
After a definitive failure (SUBMISSION_FAILED, or any other code the server
refused with) use a new key, and never reuse a key for a different payment. A
key already used for another kind of spend is refused with
SUBMISSION_KEY_REUSED.
The lookup only helps if the key reached the server. A server or iframe vault
host without submission keys would drop it, so the SDK refuses a keyed send
there with UNSUPPORTED_OPERATION before anything is sent.
Auto Re-Authentication
User-Friendly Error Messages
WASM Loading
The SDK includes a WebAssembly module for ZK proof generation. Managing how and when it loads affects initial page load time.Lazy Loading
Don’t import the SDK at the top level in routes that don’t need it:Preloading
For routes that will need the SDK, preload in the background:Code Splitting
Tree Shaking
Import only what you need:Caching & Network
Balance Caching
The SDK caches balances locally. Control refresh behavior:Request Deduplication
Avoid redundant concurrent requests:Parallel Requests
Next Steps
- Deposits — Deposit tokens into the shielded pool
- Withdrawals — Withdraw tokens from the shielded pool
- Session Storage — Session persistence and management
- API Reference — Complete method signatures and types