Skip to main content

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 extend PrivacyBoostError:

Type-Safe Error Handling

Retry with Exponential Backoff

Recovering a Lost Submit

A send or unshield whose answer was lost fails with outcomeUnknown 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.
A lookup doesn’t unwrap WETH. When it finds an 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