Errors

When an SDK call fails, it throws a VoidhashException. That includes Google Play Billing failures: the SDK converts them, so a store problem never reaches your app as another exception type, and code that catches VoidhashException (or any Exception) handles it. Every exception carries a stable, machine-matchable code string. Match on error.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:

try {
    val products = voidhash.getProducts()
} catch (error: VoidhashException) {
    if (error.code == "FAILED_TO_GET_PRODUCTS") {
        // retry, or render the screen without store metadata
    }
}

Most calls never throw because Voidhash is unreachable. Reads such as getCurrentPerson() and getFeatureFlags() answer from cached state, flush() reports what is still queued, and writes queue for later delivery. The codes below are the failures that do reach your code. The message text is informational. Never match on it.

Store codes

restorePurchases() throws RECONCILE_TRANSACTIONS_FAILED when at least one restorable receipt was not accepted. That includes a receipt still queued because Voidhash could not be reached; the SDK keeps it and delivers it in the background. It also includes a receipt the backend refused, for example because Google Play is not configured for your app's package name. Prompt the customer to try the restore again later. syncPurchases() throws it only when a receipt could not be processed at all.

Reporting codes

Purchase codes

USER_CANCELLED, PURCHASE_PENDING, PURCHASE_FAILED and BILLING_ERROR are reserved for SDK-started purchases in the later commerce launch.

Argument codes

Lifecycle codes

API codes

A write the API refuses outright throws a VoidhashApiException. It is a VoidhashException whose status and tag describe the API's answer. Branch on code and tag rather than on the status. identify(...) throws one in these cases and restores the previous identity:

A 409 (Api/SdkPersonAlreadyIdentifiedError) means the anonymous identity is already linked to another account. identify(...) does not throw for it: the device switches to the customer you identified without merging the anonymous identity, and the SDK reports PERSON_WRITE_REJECTED.

setPersonAttributes(...) throws for a payload the API refuses, such as a 400. Its "no such person" answer is not a refusal: the attributes stay queued until the person exists.

Writes that fail because Voidhash is unreachable, because an answer could not be read, or because the publishable key was rejected are queued instead and report WriteStatus.DEFERRED. INVALID_REQUEST is thrown before anything is sent, when the SDK cannot build the request at all.

Diagnostics

Failures the SDK handles on its own never throw. They are reported through the onDiagnostic option instead, as a VoidhashDiagnostic with a kind, a stable code, the operation, and whether the SDK retries. The handler runs on a background thread, one report at a time in the order they were made, and an exception it throws is ignored. Messages never contain a user ID or a purchase token.

VoidhashOptions(
    onDiagnostic = { diagnostic ->
        Log.d("Voidhash", "${diagnostic.code}: ${diagnostic.message}")
    },
)

The package README lists every code.

Next steps

• Check access
• Report and restore purchases
• Kotlin SDK reference