error-handling

Error Handling and Retry Strategies

Every Play Billing Library call can fail. Network connections drop, the Play Store app updates or restarts, users cancel purchases, and payment methods get declined. This skill gives you a phased path from reading a BillingResult to shipping a retry layer that recovers gracefully without hammering Google's servers.

Phase 1: Read BillingResult correctly

Every PBL operation returns a BillingResult with two fields. Treat them asymmetrically.

• responseCode is the integer constant you branch on. Always use the constants from BillingClient.BillingResponseCode, never the raw integer.
• debugMessage is a log only string. Google can change the text at any time, so never parse it and never show it to users.

// PBL 9.x
val billingResult = billingClient.acknowledgePurchase(params)
when (billingResult.responseCode) {
    BillingClient.BillingResponseCode.OK -> { /* proceed */ }
    BillingClient.BillingResponseCode.NETWORK_ERROR -> { /* retry */ }
    else -> Log.e("Billing", billingResult.debugMessage)
}

PBL 8.0 added sub response codes, read in PurchasesUpdatedListener with BillingResult.getOnPurchasesUpdatedSubResponseCode() (Kotlin: billingResult.onPurchasesUpdatedSubResponseCode). Two are worth branching on:

• PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS arrives under a top level ERROR and lets you suggest a different payment method instead of a generic failure screen.
• USER_INELIGIBLE tells you the user does not qualify for the offer, so you can show alternatives they do qualify for.

Not every failure carries a sub response code. Check presence before acting.

Phase 2: Classify every response code

Before you write retry code, place every code in one of four buckets. Retriable codes drive loops. User driven codes drive UI prompts. Cache sync codes drive a refresh then replay. Terminal codes surface an error message and stop.

Response Code	Value	Category	Action
OK	0	Success	Proceed
USER_CANCELED	1	Ignore	Return silently to previous screen
SERVICE_UNAVAILABLE	2	Retriable	Exponential backoff
BILLING_UNAVAILABLE	3	User driven	Show a generic unavailable message with a Try again button; never auto retry
ITEM_UNAVAILABLE	4	Cache sync	Refresh product details
DEVELOPER_ERROR	5	Terminal	Fix code, log debugMessage
ERROR	6	Retriable	Exponential backoff
ITEM_ALREADY_OWNED	7	Cache sync	Refresh purchases, grant access
ITEM_NOT_OWNED	8	Cache sync	Refresh purchases
NETWORK_ERROR	12	Retriable	Simple retry with short delay
SERVICE_DISCONNECTED	-1	Reconnect	With enableAutoServiceReconnection(): retry the call (simple in session, backoff in background). Without it: call startConnection, then retry
SERVICE_TIMEOUT	-3	Retriable (deprecated, not returned since PBL 6)	Treat as SERVICE_UNAVAILABLE
FEATURE_NOT_SUPPORTED	-2	Terminal	Hide feature in UI