SDK error codes — Voidhash Docs

Find which Voidhash SDK and area an error code comes from, and where to read more.

Every Voidhash error carries a stable code; branch on the code, never on the message. Codes in UPPER_SNAKE_CASE and Voidhash…Error names come from the client SDKs, listed here by area. Lower-case codes such as product_not_found come from the API and the server libraries; see API error codes.

How a code reaches you differs by SDK:

SDK	Carries the code in
Swift	A thrown `VoidhashStoreError` or `VoidhashApiError`.
Kotlin	A thrown `VoidhashException`.
React Native	`error.code` on a returned `Result`; it never throws. A cancelled or pending purchase is an `Ok` status.
Web	A rejected `VoidhashError` subclass whose message starts with the code.

Configuration

Code	Platforms	Meaning
`CONFIGURATION_MISSING`	Kotlin	The client is disabled, or the project configuration hasn't loaded yet.
`CLIENT_SHUT_DOWN`	Kotlin	The client was shut down or replaced by a later `configure`.
`STOREKIT_NOT_INITIALIZED`	Swift	A store call ran on a disabled or shut-down client.
`METHOD_NOT_AVAILABLE_PLATFORM`	Swift	The method isn't available here, such as store sheets in development mode.
`READ_ONLY_PURCHASE_NOT_ALLOWED`	Swift, Kotlin, React Native	The SDK is in observer mode, so it can't start a purchase.
`PRODUCT_NOT_FOUND`	Kotlin	In development mode, the product has no development data.
`FAILED_TO_INITIALIZE_VOIDHASH_CLIENT`	React Native	The binary lacks the native modules, or the native client didn't start.
`VOIDHASH_CLIENT_NOT_INITIALIZED`	React Native	A read ran before initialization finished, or it failed.
`FAILED_TO_END_VOIDHASH_CLIENT`	React Native	`end()` failed.
`INVALID_ARGUMENT`	React Native	In development builds, a `baseUrl`, `ingestUrl` or `analyticsConsent` option is invalid.
`UNKNOWN`	React Native	A hook hit an unexpected failure.
`VoidhashConfigurationError`	Web	An option is invalid, such as a missing `publishableKey` or a secret key.
`VoidhashNotInitializedError`	Web	A method ran before `initialize()`.
`VoidhashDestroyedError`	Web	The client was destroyed, for example by an unmounted provider.
`FAILED_TO_INITIALIZE`	Web	`initialize()` couldn't load saved state, for example with blocked storage.
`FAILED_TO_SET_ANALYTICS_CONSENT`	React Native, Web	React Native: the consent applies for this run but wasn't stored. Web: the value is invalid.

Details: Swift, Kotlin, React Native and Web.

Products and purchases

Purchase, restore and transaction-report codes are listed in Purchase error codes. USER_CANCELLED and PURCHASE_PENDING are expected outcomes, not failures.

Paywalls and flows

presentFlow returns these in a failed result instead of throwing.

Code	Platforms	Meaning
`FLOW_NOT_ASSIGNED`	Swift, Kotlin, React Native	Nothing is assigned to the location, it's missing or archived, or the build needs a newer SDK.
`FLOW_UNAVAILABLE`	Swift, Kotlin, React Native	The device never loaded this location and can't reach Voidhash, or the download failed.
`FLOW_RENDERER_MISSING`	Swift, Kotlin, React Native	The app was built without the paywall renderer.
`FLOW_UNSUPPORTED_PACKAGE`	Swift, Kotlin, React Native	The paywall was built in a format this SDK can't read.
`FLOW_PRESENTATION_FAILED`	Swift, Kotlin, React Native	There was no screen to present from, or the paywall couldn't be drawn.
`FLOW_DISABLED`	Swift, Kotlin, React Native	The client is disabled or shut down.
`FAILED_TO_GET_PAYWALL_FOR_LOCATION`	React Native	`getPaywallForLocation()` failed.
`PAYWALL_UNAVAILABLE`	React Native	`getPaywallForLocation()` found nothing cached and Voidhash is unreachable.

Details: Swift, Kotlin and React Native.

Identity

Code	Platforms	Meaning
`INVALID_ARGUMENT`	Swift, Kotlin, React Native	A user ID was blank, over 255 characters, contained NUL or started with `vh_anon_`; or an attribute value was nested. Nothing changed.
`IDENTITY_UNAVAILABLE`	Swift	A refresh ran before the device's first unlock, or on a shut-down client. Nothing was sent.
`VoidhashInvalidArgumentError`	Web	`identify()` got a blank or anonymous ID, or `track()` a blank event name.
`FAILED_TO_IDENTIFY`	React Native, Web	React Native: Voidhash refused the sign-in for good; the previous identity is kept. Web: the identity couldn't be switched on the device.
`FAILED_TO_SIGN_OUT`, `FAILED_TO_RESET`	React Native, Web	Signing out or resetting failed.
`FAILED_TO_GET_CURRENT_PERSON`	React Native	The person couldn't be read.
`FAILED_TO_GET_DISTINCT_ID`	React Native	The distinct ID couldn't be read.
`FAILED_TO_SET_PERSON_ATTRIBUTES`, `FAILED_TO_SET_PERSON_ATTRIBUTES_SYNC`	React Native, Web	Attributes weren't saved.
`FAILED_TO_SET_AD_DATA_SHARING`	Web	`setAdDataSharing()` couldn't record the choice.
`FAILED_TO_RESET_PERSON_CACHE`	React Native	The cached person couldn't be cleared.
`FAILED_TO_GET_FEATURE_FLAGS`	React Native, Web	Flags couldn't be evaluated.
`FAILED_TO_REFRESH_FEATURE_FLAGS`	Web	`refreshFeatureFlags()` failed.
`VoidhashFeatureFlagsError`	Web	The feature flag hook couldn't load flags.
`FAILED_TO_TRACK`	Web	`track()` or `page()` couldn't queue the event.
`FAILED_TO_FLUSH_ANALYTICS`	React Native, Web	Events weren't sent now.
`FAILED_TO_FLUSH_IDENTITY`	Web	`flushAnalytics()` couldn't send queued identity writes.

Details: Swift, Kotlin, React Native and Web.

Network and API

Most calls answer from the cache or queue when Voidhash is unreachable, so these are rare.

Code	Platforms	Meaning
`AUTHENTICATION_FAILED`	Swift, Kotlin, React Native	Voidhash answered `401` or `403`: the publishable key was rejected. Reads return it once, when nothing is cached.
`INVALID_REQUEST`	Swift, Kotlin	Swift: Voidhash answered `400`. Kotlin: no request could be built.
`NOT_FOUND`	Swift	Voidhash answered `404`, for example an unknown sign-in target.
`RATE_LIMIT_EXCEEDED`	Swift, Kotlin	Voidhash answered `429`.
`API_ERROR`	Swift, Kotlin	Any other error status. Both add the status and the error's `tag`.
`NETWORK_ERROR`	Swift, Kotlin	The request never reached Voidhash.
`INVALID_RESPONSE`, `MALFORMED_RESPONSE`	Swift, Kotlin	Voidhash's answer couldn't be read.

Details: Swift, Kotlin, React Native and Web.

Diagnostics

Diagnostics report problems the SDK handles itself through the onDiagnostic option; they never throw.

Code	Platforms	Meaning
`AUTHENTICATION_FAILED`	Swift, Kotlin, React Native, Web	The publishable key was rejected; requests pause and nothing reaches Voidhash.
`CIRCUIT_OPEN` (Web: `CIRCUIT_OPENED`)	Swift, Kotlin, React Native, Web	Voidhash failed 5 times in a row; requests pause and the cache is served.
`TRANSACTION_REJECTED`	Swift, Kotlin, React Native	Voidhash refused a purchase, for example because the store isn't set up for this bundle ID or package name.
`PERSON_WRITE_REJECTED` (Web: `IDENTITY_WRITE_REFUSED`)	Swift, Kotlin, React Native, Web	A queued `identify` or attribute update was refused, or the anonymous ID belongs to another account.
`ANALYTICS_EVENT_DROPPED`	Swift, Kotlin, React Native, Web	Events were dropped, for example at the queue limit.
`ANALYTICS_CONSENT_DENIED`	Swift, Kotlin, React Native, Web	Analytics weren't collected because consent isn't granted.

Full lists: Swift, Kotlin, React Native and Web.

Next steps

API error codes: the API, webhook verification and event capture.
Troubleshooting: causes by symptom.
FAQ

How a code reaches you differs by SDK:

SDK	Carries the code in
Swift	A thrown `VoidhashStoreError` or `VoidhashApiError`.
Kotlin	A thrown `VoidhashException`.
React Native	`error.code` on a returned `Result`; it never throws. A cancelled or pending purchase is an `Ok` status.
Web	A rejected `VoidhashError` subclass whose message starts with the code.

Configuration

Code	Platforms	Meaning
`CONFIGURATION_MISSING`	Kotlin	The client is disabled, or the project configuration hasn't loaded yet.
`CLIENT_SHUT_DOWN`	Kotlin	The client was shut down or replaced by a later `configure`.
`STOREKIT_NOT_INITIALIZED`	Swift	A store call ran on a disabled or shut-down client.
`METHOD_NOT_AVAILABLE_PLATFORM`	Swift	The method isn't available here, such as store sheets in development mode.
`READ_ONLY_PURCHASE_NOT_ALLOWED`	Swift, Kotlin, React Native	The SDK is in observer mode, so it can't start a purchase.
`PRODUCT_NOT_FOUND`	Kotlin	In development mode, the product has no development data.
`FAILED_TO_INITIALIZE_VOIDHASH_CLIENT`	React Native	The binary lacks the native modules, or the native client didn't start.
`VOIDHASH_CLIENT_NOT_INITIALIZED`	React Native	A read ran before initialization finished, or it failed.
`FAILED_TO_END_VOIDHASH_CLIENT`	React Native	`end()` failed.
`INVALID_ARGUMENT`	React Native	In development builds, a `baseUrl`, `ingestUrl` or `analyticsConsent` option is invalid.
`UNKNOWN`	React Native	A hook hit an unexpected failure.
`VoidhashConfigurationError`	Web	An option is invalid, such as a missing `publishableKey` or a secret key.
`VoidhashNotInitializedError`	Web	A method ran before `initialize()`.
`VoidhashDestroyedError`	Web	The client was destroyed, for example by an unmounted provider.
`FAILED_TO_INITIALIZE`	Web	`initialize()` couldn't load saved state, for example with blocked storage.
`FAILED_TO_SET_ANALYTICS_CONSENT`	React Native, Web	React Native: the consent applies for this run but wasn't stored. Web: the value is invalid.

Details: Swift, Kotlin, React Native and Web.

Products and purchases

Purchase, restore and transaction-report codes are listed in Purchase error codes. USER_CANCELLED and PURCHASE_PENDING are expected outcomes, not failures.

Paywalls and flows

presentFlow returns these in a failed result instead of throwing.

Code	Platforms	Meaning
`FLOW_NOT_ASSIGNED`	Swift, Kotlin, React Native	Nothing is assigned to the location, it's missing or archived, or the build needs a newer SDK.
`FLOW_UNAVAILABLE`	Swift, Kotlin, React Native	The device never loaded this location and can't reach Voidhash, or the download failed.
`FLOW_RENDERER_MISSING`	Swift, Kotlin, React Native	The app was built without the paywall renderer.
`FLOW_UNSUPPORTED_PACKAGE`	Swift, Kotlin, React Native	The paywall was built in a format this SDK can't read.
`FLOW_PRESENTATION_FAILED`	Swift, Kotlin, React Native	There was no screen to present from, or the paywall couldn't be drawn.
`FLOW_DISABLED`	Swift, Kotlin, React Native	The client is disabled or shut down.
`FAILED_TO_GET_PAYWALL_FOR_LOCATION`	React Native	`getPaywallForLocation()` failed.
`PAYWALL_UNAVAILABLE`	React Native	`getPaywallForLocation()` found nothing cached and Voidhash is unreachable.

Details: Swift, Kotlin and React Native.

Identity

Code	Platforms	Meaning
`INVALID_ARGUMENT`	Swift, Kotlin, React Native	A user ID was blank, over 255 characters, contained NUL or started with `vh_anon_`; or an attribute value was nested. Nothing changed.
`IDENTITY_UNAVAILABLE`	Swift	A refresh ran before the device's first unlock, or on a shut-down client. Nothing was sent.
`VoidhashInvalidArgumentError`	Web	`identify()` got a blank or anonymous ID, or `track()` a blank event name.
`FAILED_TO_IDENTIFY`	React Native, Web	React Native: Voidhash refused the sign-in for good; the previous identity is kept. Web: the identity couldn't be switched on the device.
`FAILED_TO_SIGN_OUT`, `FAILED_TO_RESET`	React Native, Web	Signing out or resetting failed.
`FAILED_TO_GET_CURRENT_PERSON`	React Native	The person couldn't be read.
`FAILED_TO_GET_DISTINCT_ID`	React Native	The distinct ID couldn't be read.
`FAILED_TO_SET_PERSON_ATTRIBUTES`, `FAILED_TO_SET_PERSON_ATTRIBUTES_SYNC`	React Native, Web	Attributes weren't saved.
`FAILED_TO_SET_AD_DATA_SHARING`	Web	`setAdDataSharing()` couldn't record the choice.
`FAILED_TO_RESET_PERSON_CACHE`	React Native	The cached person couldn't be cleared.
`FAILED_TO_GET_FEATURE_FLAGS`	React Native, Web	Flags couldn't be evaluated.
`FAILED_TO_REFRESH_FEATURE_FLAGS`	Web	`refreshFeatureFlags()` failed.
`VoidhashFeatureFlagsError`	Web	The feature flag hook couldn't load flags.
`FAILED_TO_TRACK`	Web	`track()` or `page()` couldn't queue the event.
`FAILED_TO_FLUSH_ANALYTICS`	React Native, Web	Events weren't sent now.
`FAILED_TO_FLUSH_IDENTITY`	Web	`flushAnalytics()` couldn't send queued identity writes.

Details: Swift, Kotlin, React Native and Web.

Network and API

Most calls answer from the cache or queue when Voidhash is unreachable, so these are rare.

Code	Platforms	Meaning
`AUTHENTICATION_FAILED`	Swift, Kotlin, React Native	Voidhash answered `401` or `403`: the publishable key was rejected. Reads return it once, when nothing is cached.
`INVALID_REQUEST`	Swift, Kotlin	Swift: Voidhash answered `400`. Kotlin: no request could be built.
`NOT_FOUND`	Swift	Voidhash answered `404`, for example an unknown sign-in target.
`RATE_LIMIT_EXCEEDED`	Swift, Kotlin	Voidhash answered `429`.
`API_ERROR`	Swift, Kotlin	Any other error status. Both add the status and the error's `tag`.
`NETWORK_ERROR`	Swift, Kotlin	The request never reached Voidhash.
`INVALID_RESPONSE`, `MALFORMED_RESPONSE`	Swift, Kotlin	Voidhash's answer couldn't be read.

Details: Swift, Kotlin, React Native and Web.

Diagnostics

Diagnostics report problems the SDK handles itself through the onDiagnostic option; they never throw.

Code	Platforms	Meaning
`AUTHENTICATION_FAILED`	Swift, Kotlin, React Native, Web	The publishable key was rejected; requests pause and nothing reaches Voidhash.
`CIRCUIT_OPEN` (Web: `CIRCUIT_OPENED`)	Swift, Kotlin, React Native, Web	Voidhash failed 5 times in a row; requests pause and the cache is served.
`TRANSACTION_REJECTED`	Swift, Kotlin, React Native	Voidhash refused a purchase, for example because the store isn't set up for this bundle ID or package name.
`PERSON_WRITE_REJECTED` (Web: `IDENTITY_WRITE_REFUSED`)	Swift, Kotlin, React Native, Web	A queued `identify` or attribute update was refused, or the anonymous ID belongs to another account.
`ANALYTICS_EVENT_DROPPED`	Swift, Kotlin, React Native, Web	Events were dropped, for example at the queue limit.
`ANALYTICS_CONSENT_DENIED`	Swift, Kotlin, React Native, Web	Analytics weren't collected because consent isn't granted.

Full lists: Swift, Kotlin, React Native and Web.

Next steps

API error codes: the API, webhook verification and event capture.
Troubleshooting: causes by symptom.
FAQ