Errors

The Swift SDK throws errors with a stable code: StoreKit failures are wrapped in the SDK's own codes, and Voidhash API failures are mapped from the HTTP status.

Handle errors

Methods that can fail are async throws. Catch the error type, then branch on code. The error's string form is "CODE: message"; the message is for people, so never match on it.

import Voidhash
import VoidhashCore

func buy(_ product: VoidhashProduct) async {
    guard let voidhash = Voidhash.shared else { return }
    do {
        try await voidhash.purchase(product: product)
    } catch let error as VoidhashStoreError {
        switch error.code {
        case "USER_CANCELLED", "PURCHASE_PENDING":
            break // Expected outcomes, not failures.
        case "OFFER_UNAVAILABLE":
            showRegularPrice()
        default:
            showPurchaseError(error)
        }
    } catch {
        showPurchaseError(error)
    }
}

Most calls don't throw when Voidhash is unreachable: reads answer from the cache and writes are queued. Failures the SDK handles itself arrive as diagnostics instead.

Error types

Error codes

Configuration

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

Products and purchases

purchase(product:) and purchase(productSlug:) throw USER_CANCELLED and PURCHASE_PENDING as expected outcomes; handle them apart from failures.

Passing an unverified StoreKit result to reportTransaction(_:) rethrows StoreKit's verification error.

Paywalls and flows

presentFlow never throws. It returns .failed(FlowError); match on the case.

A purchase started on a paywall reports its failures through onWarning and shows them on the paywall. A cancelled purchase isn't reported. See When nothing is shown.

Identity

identify and setPersonAttributes don't throw for network failures or a rejected key: the SDK saves the write and sends it later. They throw a VoidhashApiError only when Voidhash refuses the write for good within the 2 seconds the call waits; identify then restores the previous identity.

Network and API

VoidhashApiError maps the HTTP status to a code. These are rarely thrown, since reads fall back to the cache and writes are queued; they also appear as the code of transport diagnostics.

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

Diagnostics report failures the SDK handled itself, such as a delivery it will retry. They never throw. Receive them with the onDiagnostic option; onWarning gets the same situations as text. Diagnostic codes lists every code.

Next steps

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