Skip to content
AppDues
Log in
Contact salesSign up

Google Play Billing Library Error Handling: Retry, Backoff and Reconnect Decisions

Google Play Billing Library connects an Android app to the Play Store for product queries, purchases and subscription management. A BillingClient connection is reported through setup and disconnection callbacks, and the connection can drop at any time. The practical task is to decide, for each error and each call site, whether to retry immediately, retry with growing delays, reconnect first, refresh state, or stop and surface the problem.

How the BillingClient lifecycle shapes error handling

Start from the connection lifecycle. A successful setup means the app can call operations such as launchBillingFlow, queryProductDetailsAsync and queryPurchasesAsync. Setup completion and service disconnection are separate callbacks, so a design that only checks connection state at call time can miss a drop that happens between the check and the request. A useful checklist is: confirm setup outcome, handle disconnection as a distinct event, and decide per operation whether a fresh connection attempt is required before any retry.

Why unbounded backoff and callback-driven reconnects fail

An early approach used exponential backoff for reconnection and checked connection state before interacting, without retrying on disconnection except when a later interaction discovered the drop. That left two weaknesses. First, backoff retries could run indefinitely in a broken state. Second, a device-language change while connected was a reproducible trigger: the service disconnected and would not reconnect until the device restarted or Play caches were cleared. A related Samsung-only +999 intent connection failure was reported but never reproduced, and was suspected to be connected to endless reconnection attempts. The lesson is to bound every retry, test locale and cache changes during development, and treat repeated disconnection callbacks as a warning sign rather than a reason to reconnect forever.

Five response patterns to choose from

Five response patterns cover most cases. Simple retry repeats the request promptly, up to a small limit. Exponential backoff spaces attempts with increasing delays, capped in the implementation described here at 15 minutes. Reconnect and retry re-establishes the connection before repeating the request. Propagate error hands the failure to the developer or user. Call and return error makes a different call, such as a purchase query or feature check, and bases the next step on that result. Choosing among these five patterns per error is clearer than applying one global retry rule.

Retryable errors: match the retry style to the call site

For NETWORK_ERROR and ERROR, use a simple retry when the user is actively in session and exponential backoff when the work was started without user interaction. Product detail queries, billing-flow launches and restores used simple retries, capped at three attempts. Startup purchase queries and in-app messages used backoff because they run without a user waiting. Consume and acknowledge calls used simple retry when triggered by a purchase or restore, and backoff otherwise. SERVICE_UNAVAILABLE used backoff in the background and surfaced an error in session; background was the test for whether the user was in an active session. SERVICE_DISCONNECTED calls for reconnect and retry in general guidance, but the implementation below explains an important exception.

Non-retryable errors: stop and surface the cause

BILLING_UNAVAILABLE, FEATURE_NOT_SUPPORTED, USER_CANCELED, DEVELOPER_ERROR and ITEM_UNAVAILABLE were not retried automatically; the error was sent to the client. The next step differs by cause: verify feature support with isFeatureSupported, refresh product details with queryProductDetailsAsync and check eligibility configuration, review the debug message and correct API usage, or let the user address billing or cancellation. Retrying these cases hides actionable problems and can loop against a state the user or developer must change first.

The BILLING_UNAVAILABLE loop: a failure distinction to preserve

In a broken cache state, a single startConnection call could produce many setup callbacks, alternating between OK and BILLING_UNAVAILABLE, plus repeated disconnection callbacks. Retrying on each disconnection or on each BILLING_UNAVAILABLE setup result therefore created a reconnection loop, and endConnection did not stop the extra disconnection callbacks; only quitting the app did. The safer rule used here is to retry connectivity when the client is found disconnected at interaction time, not automatically on every disconnection callback, and not to retry BILLING_UNAVAILABLE from setup. A specific message about the in-app billing API version being less than 3 was also matched to improve the error shown in that state.

Ownership refresh, duplicate responses and the +999 case

ITEM_ALREADY_OWNED can appear when launching a billing flow, and ITEM_NOT_OWNED can appear when consuming or acknowledging. The recommended response is to query purchases again and confirm ownership from fresh data before deciding. That refresh step was not yet implemented in the implementation described, so it should be treated as a planned improvement rather than completed behaviour. Separately, duplicate responses can arrive for one call, such as two OK results for a product detail query. Guard the listener with an atomic flag so only the first response reaches the caller and later duplicates are logged and dropped. For the unreproduced Samsung +999 case, an IllegalStateException from startConnection was caught and converted into a clearer error message.

Per-call decision checklist

Before shipping, run this decision checklist for every BillingClient call: name the operation and whether a user is waiting; classify the error as retryable, refresh-first, or propagate; choose simple retry, capped backoff, reconnect-then-retry, or no retry; set a maximum attempt count and maximum delay; ensure only one response is delivered to the caller; and test the language-change and cache-clear scenario plus a background SERVICE_UNAVAILABLE case. If any answer is missing, the error path is not finished.

Error response reference
ErrorRecommended response
NETWORK_ERRORExponential backoff or simple retry when users are in session
SERVICE_TIMEOUT (not returned in BC6)Exponential backoff or simple retry in session; BC6 returns SERVICE_UNAVAILABLE
SERVICE_DISCONNECTEDExponential backoff or simple retry in session; re-establish connection using BillingClient.startConnection
SERVICE_UNAVAILABLEExponential backoff when users are not in session; error out in session
BILLING_UNAVAILABLEManual retry after user addresses the issue
ERRORExponential backoff or simple retry when users are in session
ITEM_ALREADY_OWNEDSimple retry logic after calling BillingClient.queryPurchasesAsync
ITEM_NOT_OWNEDSimple retry logic after calling BillingClient.queryPurchasesAsync
FEATURE_NOT_SUPPORTEDCheck feature support using BillingClient.isFeatureSupported
USER_CANCELEDNo retry mechanism listed
ITEM_UNAVAILABLERefresh product details using BillingClient.queryProductDetailsAsync and check product eligibility configuration
DEVELOPER_ERROREnsure correct use of Play Billing Library calls and check debug message

Qualifications from the captured tables and implementation notes are preserved in the prose sections; SERVICE_TIMEOUT is noted as not returned in BC6, with SERVICE_UNAVAILABLE returned instead.

Frequently asked questions

Which Billing Library errors are worth retrying?

Retry only when the failure can plausibly clear: transient network or generic errors, and a dropped service connection. For a dropped connection, re-establish it with BillingClient.startConnection and then repeat the request. Do not automatically retry on every disconnection callback, because repeated callbacks can create a reconnection loop.

Which errors should not be retried automatically?

Do not retry automatically. Surface the error so the user or developer can act: check feature support, refresh product details and eligibility, correct the API usage, or let the user decide after a cancellation or billing problem.

What should happen after ITEM_ALREADY_OWNED or ITEM_NOT_OWNED?

Treat the call as a signal to re-check ownership. Call queryPurchasesAsync again and decide from the refreshed list, rather than assuming the first response is final.

How can duplicate BillingClient responses be handled?

Guard the listener so only the first response is delivered and later duplicates are logged and ignored. Duplicate callbacks were observed even for a single request.