Errors

The React Native SDK does not throw. Every failure is a VoidhashError with a stable, machine-matchable code string, and client methods deliver it as a value instead of rejecting. Each method returns a better-result Result: a success lands on the Ok side, and a failure lands on the Err side with the error attached. The code tells you which operation failed and what to do next. Match on error.code when the recovery differs by cause, and report the full error for everything else.

This example checks the result for one specific code:

const result = await voidhash.client.getProducts();
if (result.isErr() && result.error.code === "FAILED_TO_GET_PRODUCTS") {
  // retry, fall back to cached products, …
}

Hooks surface the same errors through their error field instead of throwing.

Operation codes

These codes name the client operation that failed. The message text is informational. Never match on it.

Code	Returned by	Recovery guidance
`FAILED_TO_INITIALIZE_VOIDHASH_CLIENT`	`init()`	Show a retry screen that calls `useVoidhash().retryInit`.
`FAILED_TO_CAPTURE_STARTUP_EVENTS`	`init()` analytics step	Non-fatal. The SDK logs it as a warning.
`FAILED_TO_SETUP_LIFECYCLE_EVENTS`	`init()` lifecycle step	Non-fatal for reads, but automatic lifecycle events are missing.
`FAILED_TO_END_VOIDHASH_CLIENT`	`end()`	Log it and continue teardown.
`FAILED_TO_FETCH_SCHEMA`	`init()` on a cold cache	Check connectivity. The next launch retries.
`FAILED_TO_GET_CURRENT_PERSON`	`getCurrentPerson()`, `hasPerk()`	Serve cached state. See Check access.
`FAILED_TO_SET_PERSON_ATTRIBUTES`	`setPersonAttributes()`	Retry later. Attributes ride the analytics queue.
`FAILED_TO_SET_PERSON_ATTRIBUTES_SYNC`	`setPersonAttributesSync()`	Retry. Check for read-only mode first (`READ_ONLY_PURCHASE_NOT_ALLOWED`).
`FAILED_TO_RESET_PERSON_CACHE`	`resetCache()`	Safe to ignore. The cache expires on its own.
`FAILED_TO_GET_DISTINCT_ID`	`getDistinctId()`	Retry after init completes.
`FAILED_TO_IDENTIFY`	`identify()`	Retry. An already-identified person surfaces this code too.
`FAILED_TO_RESET`	`reset()`	Retry.
`FAILED_TO_SIGN_OUT`	`signOut()`	Retry.
`FAILED_TO_GET_FEATURE_FLAGS`	`getFeatureFlags()`	Fall back to your default values.
`FAILED_TO_GET_PRODUCTS`	`getProducts()`	Retry, or render the screen without store metadata.
`FAILED_TO_PURCHASE`	`purchase()`	Reserved for the later commerce launch.
`FAILED_TO_RESTORE_PURCHASES`	`restorePurchases()`	Prompt the customer to retry.
`FAILED_TO_REPORT_TRANSACTION`	`reportTransaction(...)`	Supply a valid Apple transaction ID or Google Play purchase token.
`FAILED_TO_SYNC_PURCHASES`	`syncPurchases()`	Inspect the store error and retry. Captured receipts with delivery failures remain queued.
`FAILED_TO_FLUSH_ANALYTICS`	`flush()`	Nothing to do. Events stay queued and flush later.
`FAILED_TO_PRESENT_CODE_REDEMPTION_SHEET`	iOS redemption sheet	iOS only. Verify the offer code configuration.
`FAILED_TO_SHOW_MANAGE_SUBSCRIPTIONS`	iOS manage subscriptions	iOS only. Requires iOS 15 or later.

Client-state codes

These codes describe the state of the client rather than a single operation:

Code	Meaning
`VOIDHASH_CLIENT_NOT_INITIALIZED`	A method ran before the provider finished `init()`. Gate calls on `useVoidhash().status === "ready"`.
`READ_ONLY_PURCHASE_NOT_ALLOWED`	Purchase initiation is unavailable in the observer-only release.
`SCHEME_NOT_SET`	Reserved for paywall callback configuration.
`UNSUPPORTED_PLATFORM`	A platform-specific method ran on a platform it does not support, such as an iOS-only call on Android.
`UNKNOWN`	An unexpected failure. Report the full error.

Purchase availability

purchase() currently returns an Err before the native store is touched. The error carries the code READ_ONLY_PURCHASE_NOT_ALLOWED, which means purchase initiation is unavailable in the observer-only release.

Operation codes

Client-state codes

Purchase availability

Next steps