Billing Response Codes

Billing Response Codes

Phase 0: Intent

Use 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:

• All BillingResponseCode constants defined in PBL 9.x (the constant set is unchanged from PBL 8.x; v9 added no codes and removed none).
• All OnPurchasesUpdatedSubResponseCode constants added in PBL 8.0.
• Retry eligibility for each code.
• The recommended response strategy per code.
• A decision tree that maps any received code to an action.

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.

Phase 1: Locate

The authoritative copy of the tables and decision tree lives in the full appendix on revenuecat.com. When a question asks for:

• The literal integer value of a code, see "Response Codes".
• Sub response codes introduced in PBL 8.0, see "Sub Response Codes (PBL 8.0+)".
• The retry strategy for a code, see "Retry Implementation Summary".
• A full flow from received code to action, see "Error Handling Decision Tree".

The tables reproduced below in Phase 2 mirror the appendix verbatim so you can answer most lookups without opening the chapter.

Phase 2: Reference Tables

BillingResponseCode values

Sub Response Codes (PBL 8.0+)

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().

Accessing sub response codes

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)
        }
    }
}

Retry strategy summary

Phase 3: Handling Guidance

When you receive a BillingResult, walk it through this decision tree:

1. Is responseCode equal to OK?

   • Yes: process the result. Done.
   • No: continue.

2. Is responseCode equal to USER_CANCELED?

   • Yes: do nothing. The user chose to cancel. Done.
   • No: continue.

3. Is the error retriable? (SERVICE_UNAVAILABLE, ERROR, NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_TIMEOUT)

   • Yes: retry with the matching strategy from the retry summary table. Simple retry for NETWORK_ERROR, exponential backoff for service errors. If all retries fail, show an error message.
   • No: continue.

4. Is it a cache sync issue? (ITEM_ALREADY_OWNED, ITEM_NOT_OWNED)

   • Yes: call queryPurchasesAsync() to refresh your purchase cache. Update UI accordingly.
   • No: continue.

5. Is it a product issue? (ITEM_UNAVAILABLE)

   • Yes: refresh product details. The product may no longer be available.
   • No: continue.

6. Is it a device or environment issue? (BILLING_UNAVAILABLE, FEATURE_NOT_SUPPORTED)

   • Yes: show a user facing message. Do not retry automatically. Let the user initiate a retry.
   • No: continue.

7. Is it a developer error? (DEVELOPER_ERROR)

   • Yes: log the error with full details. Fix the API usage in your code. This should not happen in production.

Category quick reference

Group each code into one of six buckets so you can route it to the right handler:

• Success: OK.
• User intent: USER_CANCELED.
• Transient service or network: SERVICE_UNAVAILABLE, ERROR, NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_TIMEOUT.
• Cache sync: ITEM_ALREADY_OWNED, ITEM_NOT_OWNED.
• Catalog or product: ITEM_UNAVAILABLE.
• Environment or configuration: BILLING_UNAVAILABLE, FEATURE_NOT_SUPPORTED.
• Programming error: DEVELOPER_ERROR.

Checking a code with when

fun 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
}

References

• Full chapter

• 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