Terminal
Terminal/Skill
Reference lookup for every Play Billing Library response code and sub response code, with retry eligibility and recommended handling.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill billing-response-codesUse this skill when you need to look up the meaning, category, or handling strategy for a value returned by BillingResult.getResponseCode() or BillingResult.getOnPurchasesUpdatedSubResponseCode() in the Play Billing Library. This reference covers:
BillingResponseCode constants defined in PBL 9.x (the constant set is unchanged from PBL 8.x; v9 added no codes and removed none).OnPurchasesUpdatedSubResponseCode constants added in PBL 8.0.Use this skill to answer questions like "what does response code 7 mean", "should I retry on SERVICE_UNAVAILABLE", or "how do I handle ITEM_ALREADY_OWNED".
Do not use this skill to author new integration code from scratch. Use the launch or purchase flow skills for that. This skill is a lookup table.
The authoritative copy of the tables and decision tree lives in the full appendix on revenuecat.com. When a question asks for:
The tables reproduced below in Phase 2 mirror the appendix verbatim so you can answer most lookups without opening the chapter.
| Code | Value | Retriable | Description | Recommended Strategy |
|---|---|---|---|---|
OK | 0 | N/A | Operation succeeded | Process the result normally. |
USER_CANCELED | 1 | No | User dismissed the purchase dialog | No action needed. Do not show an error message. |
SERVICE_UNAVAILABLE | 2 | Yes | Google Play service is temporarily unavailable | Retry with exponential backoff (2s base, 2x factor, max 3 attempts). |
BILLING_UNAVAILABLE | 3 | No (auto) | Billing is unavailable on this device or for this user | Do not auto retry. Check Play Store version and user account. Let the user try again manually. PBL 9 (with androidx.core 1.9+) also routes a system blocked Play Store here with a "Play Store is blocked" debugMessage, where PBL 8 returned ERROR. |
ITEM_UNAVAILABLE | 4 | No | The requested product is not available for purchase | Refresh product details with queryProductDetailsAsync(). The product may have been deactivated. |
DEVELOPER_ERROR | 5 | No | Invalid arguments passed to the API | Fix your code. Check product IDs, offer tokens, and parameter construction. This is a programming error. |
ERROR | 6 | Yes | An internal Google Play error occurred | Retry with exponential backoff. If persistent, report to Google. |
ITEM_ALREADY_OWNED | 7 | No | The user already owns this non consumable item | Call queryPurchasesAsync() to refresh your local purchase cache. The user may have purchased on another device. |
ITEM_NOT_OWNED | 8 | No | Attempted to consume or acknowledge an item the user does not own | Call queryPurchasesAsync() to refresh your local purchase cache. The purchase may have been refunded. |
NETWORK_ERROR | 12 | Yes | A network error occurred during the operation | Retry with a short delay (1-2 seconds). Check device connectivity. |
SERVICE_DISCONNECTED | -1 | Yes | The BillingClient is not connected to Google Play Services | With enableAutoServiceReconnection() (PBL 8), the library retries automatically. Without it, call startConnection() and retry. |
FEATURE_NOT_SUPPORTED | -2 | No | The requested feature is not supported on this device or Play Store version | Check isFeatureSupported() before calling feature specific APIs. Provide fallback behavior. |
SERVICE_TIMEOUT | -3 | Yes (Deprecated) | The request timed out | Deprecated in recent PBL versions. Treat as SERVICE_UNAVAILABLE and retry with backoff. |
Sub response codes provide more granular information about why a purchase failed. They are only available in the PurchasesUpdatedListener.onPurchasesUpdated() callback, retrieved via BillingResult.getOnPurchasesUpdatedSubResponseCode().
| Sub Response Code | Description | When It Appears | Recommended Action |
|---|---|---|---|
NO_APPLICABLE_SUB_RESPONSE_CODE | No specific sub response applies | Default value for most responses | Handle based on the main response code only. |
PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS | User's available funds are less than the purchase price | When the main response indicates a payment failure | Show a message suggesting the user check their payment method balance. |
USER_INELIGIBLE | User does not meet eligibility requirements for an offer | When the user attempts to use an offer they are not eligible for | Show standard pricing without the offer. Check your offer eligibility logic. |
val listener = PurchasesUpdatedListener { billingResult, purchases ->
if (billingResult.responseCode != BillingResponseCode.OK) {
val subCode = billingResult.onPurchasesUpdatedSubResponseCode
when (subCode) {
OnPurchasesUpdatedSubResponseCode.PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS ->
showInsufficientFundsMessage()
OnPurchasesUpdatedSubResponseCode.USER_INELIGIBLE ->
showStandardPricing()
else -> handleGeneralError(billingResult)
}
}
}
| Strategy | Base Delay | Factor | Max Attempts | Use For |
|---|---|---|---|---|
| Simple retry | 1-2 seconds | 1x (fixed) | 3 | NETWORK_ERROR |
| Exponential backoff | 2 seconds | 2x | 3 | SERVICE_UNAVAILABLE, ERROR, SERVICE_TIMEOUT |
| Auto reconnect | Handled by PBL 8 | N/A | N/A | SERVICE_DISCONNECTED |
| User initiated | N/A | N/A | N/A | BILLING_UNAVAILABLE |
| No retry | N/A | N/A | N/A | USER_CANCELED, DEVELOPER_ERROR, FEATURE_NOT_SUPPORTED |
When you receive a BillingResult, walk it through this decision tree:
Is responseCode equal to OK?
Is responseCode equal to USER_CANCELED?
Is the error retriable? (SERVICE_UNAVAILABLE, ERROR, NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_TIMEOUT)
NETWORK_ERROR, exponential backoff for service errors. If all retries fail, show an error message.Is it a cache sync issue? (ITEM_ALREADY_OWNED, ITEM_NOT_OWNED)
queryPurchasesAsync() to refresh your purchase cache. Update UI accordingly.Is it a product issue? (ITEM_UNAVAILABLE)
Is it a device or environment issue? (BILLING_UNAVAILABLE, FEATURE_NOT_SUPPORTED)
Is it a developer error? (DEVELOPER_ERROR)
Group each code into one of six buckets so you can route it to the right handler:
OK.USER_CANCELED.SERVICE_UNAVAILABLE, ERROR, NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_TIMEOUT.ITEM_ALREADY_OWNED, ITEM_NOT_OWNED.ITEM_UNAVAILABLE.BILLING_UNAVAILABLE, FEATURE_NOT_SUPPORTED.DEVELOPER_ERROR.whenfun classify(code: Int): Category = when (code) {
BillingResponseCode.OK -> Category.SUCCESS
BillingResponseCode.USER_CANCELED -> Category.USER_INTENT
BillingResponseCode.SERVICE_UNAVAILABLE,
BillingResponseCode.ERROR,
BillingResponseCode.NETWORK_ERROR,
BillingResponseCode.SERVICE_DISCONNECTED,
BillingResponseCode.SERVICE_TIMEOUT -> Category.TRANSIENT
BillingResponseCode.ITEM_ALREADY_OWNED,
BillingResponseCode.ITEM_NOT_OWNED -> Category.CACHE_SYNC
BillingResponseCode.ITEM_UNAVAILABLE -> Category.CATALOG
BillingResponseCode.BILLING_UNAVAILABLE,
BillingResponseCode.FEATURE_NOT_SUPPORTED -> Category.ENVIRONMENT
BillingResponseCode.DEVELOPER_ERROR -> Category.PROGRAMMING
else -> Category.UNKNOWN
}
Google Play Billing Library reference for BillingResponseCode: https://developer.android.com/reference/com/android/billingclient/api/BillingClient.BillingResponseCode
Google Play Billing Library reference for OnPurchasesUpdatedSubResponseCode: https://developer.android.com/reference/com/android/billingclient/api/BillingClient.OnPurchasesUpdatedSubResponseCode