Errors

The Kotlin SDK throws a VoidhashException with a stable code: Google Play Billing failures are mapped to the SDK's own codes, and Voidhash API failures are mapped from the HTTP status.

Handle errors

Suspending methods throw on failure. Rethrow CancellationException so coroutine cancellation keeps working, then branch on code. The message is for people; never match on it.

import com.voidhash.sdk.VoidhashException
import kotlinx.coroutines.CancellationException

lifecycleScope.launch {
    try {
        voidhash.purchase(activity, monthly)
    } catch (error: CancellationException) {
        throw error
    } catch (error: VoidhashException) {
        when (error.code) {
            "USER_CANCELLED", "PURCHASE_PENDING" -> Unit // Expected outcomes, not failures.
            "OFFER_UNAVAILABLE" -> showRegularPrice()
            else -> showPurchaseError(error)
        }
    }
}

Most calls don't throw when Voidhash is unreachable: reads answer from the cache, writes are queued, and flush() reports what is still pending. Failures the SDK handles itself are diagnostics.

Error types

Error codes

Configuration

AUTHENTICATION_FAILED, a rejected publishable key, is listed under Network and API.

Products and purchases

syncPurchases() throws RECONCILE_TRANSACTIONS_FAILED only when a purchase couldn't be processed at all; restorePurchases() also throws it while a purchase is still queued, or when Voidhash hasn't answered within 10 seconds. The restore then continues in the background.

When Google Play reported the failure, the exception's cause is a BillingEngineException whose responseCode is Google Play's own response code.

Paywalls and flows

presentFlow never throws. It returns FlowResult.Failed, whose error.reason names the cause.

See Handle failures.

Identity

identify throws a VoidhashApiException with code API_ERROR when Voidhash refuses the sign-in, and restores the previous identity. Its tag is Api/SdkValidationError (400) or Api/SdkPersonNotFoundError (404). A 409 doesn't throw. Writes that fail because Voidhash is unreachable, unreadable, rejects the key, or takes longer than 2 seconds are queued and return WriteStatus.DEFERRED.

Network and API

A 401 or 403 from something in front of Voidhash, such as a proxy, a firewall or an edge page, isn't a rejected key. The SDK treats it as a temporary failure: it retries, and nothing pauses.

Diagnostics

Failures the SDK handles itself never throw. Receive them with the onDiagnostic option as a VoidhashDiagnostic with a kind, code, operation, message, and whether the SDK retries. The handler runs on one background thread, in order; exceptions it throws are ignored. Messages never contain a user ID or purchase token.

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

Diagnostic codes lists every code and what it means.

Next steps

• Troubleshooting by symptom.
• Make and restore purchases.
• Error codes across platforms.