Errors

When an SDK call fails, it throws. Every error the SDK throws is a typed error that carries a code string, and its string form is "CODE: message". The code tells you which operation failed and what to do next. Match on code when the recovery differs by cause, and report the full error for everything else.

This example handles one specific code and lets every other error propagate:

do {
    let products = try await voidhash.getProducts()
} catch let error as VoidhashStoreError where error.code == "FAILED_TO_GET_PRODUCTS" {
    // retry, fall back to cached products, …
}

Operation codes

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

Code	Thrown by	Recovery guidance
`AUTHENTICATION_FAILED`	`getCurrentPerson()`, `getFeatureFlags()`	Check the publishable key. Thrown once, only when nothing is cached.
`CONFIGURATION_MISSING`	Embedded calls on a disabled or replaced client	Call the client that replaced it.
`FAILED_TO_GET_PRODUCTS`	`getProducts()`	Retry, or render the screen without store metadata.
`FAILED_TO_RESTORE_PURCHASES`	`restorePurchases()`	The App Store could not be reached. Prompt the customer to retry.
`FAILED_TO_SHOW_MANAGE_SUBSCRIPTIONS`	`showManageSubscriptions()`	Link to the App Store subscription settings instead.
`INVALID_ARGUMENT`	`identify()`	Pass an ID Voidhash accepts. The current identity is unchanged.
`INVALID_ARGUMENT`	`setPersonAttributes()`	Pass only strings, numbers, booleans, or `nil`. Nothing is saved.
`INVALID_TRANSACTION`	`reportTransaction(...)`	Supply a non-empty original App Store transaction ID.
`RECONCILE_TRANSACTIONS_FAILED`	`restorePurchases()`	Prompt the customer to retry.
`USER_CANCELLED`	`restorePurchases()`	The customer dismissed the App Store sign-in. Do nothing.

StoreKit errors never reach your app directly: the SDK wraps them in these codes and keeps StoreKit's description in the message. Passing an unverified StoreKit result to reportTransaction(...) throws its verification error.

identify() and setPersonAttributes() do not throw for network failures or a rejected publishable key: the SDK saves the write and sends it later. They throw a VoidhashApiError only when Voidhash rejects the write for good, and a rejected identify() restores the previous identity. An anonymous ID that already belongs to a different account is not an error: identify() signs the customer in without that ID's history and reports the PERSON_WRITE_REJECTED diagnostic. When Voidhash rejects a write the SDK had saved for later, it drops it and reports the same diagnostic.

Purchase availability

purchase(product:) currently throws before StoreKit 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

Purchase availability

Next steps