RevenueCat

Build With RevenueCat

Build a customized mobile subscription business with RevenueCat. We do the heavy lifting of normalizing subscribers from any source and maintain a single source of truth for subscription status, so you can get back to building your app.

RevenueCat is a powerful, secure, reliable, and free to use in-app purchase server with global support. All you need to get started is an API key.

Error Handling

Handling errors in Purchases SDK

This section assumes you've followed our Quickstart section of our Getting Started guide to install and configure our SDK.

If the completion callbacks or listeners on asynchronous methods receive an error argument that is not nil, an error has occurred.

With the exception of NetworkError, PurchaseCancelledError or StoreProblemError, retrying a failed operation with the same arguments won't succeed. For failed purchases, assume the user wasn't charged, unless a StoreProblemError occurred - in which case the user may or may not have been charged.

iOS Errors

On iOS, when an error has occurred the completion callback will receive an NSError object.

When investigating or logging errors, review the userInfo dictionary, paying attention to the following keys:

  • RCReadableErrorCodeKey contains a cross-platform error name string that can be used for identifying the error.
  • NSLocalizedDescriptionKey contains a description of the error. This description is meant for the developer.
  • NSUnderlyingErrorKey contains the underlying error that caused the error in question, if an underlying error is present.

Examples:

if let err = error as NSError? {
                
    // log error details
    print("Error: \(err.userInfo[ReadableErrorCodeKey])")
    print("Message: \(err.localizedDescription)")
    print("Underlying Error: \(err.userInfo[NSUnderlyingErrorKey])")

    // handle specific errors
    switch PurchasesErrorCode(_nsError: err).code {
    case .purchaseNotAllowedError:
        showAlert("Purchases not allowed on this device.")
    case .purchaseInvalidError:
        showAlert("Purchase invalid, check payment source.")
    default:
        break
    }
}
if (error) {

    // log error details
    NSLog(@"RCError: %@", [error.userInfo objectForKey:RCReadableErrorCodeKey]);
    NSLog(@"Message: %@", error.localizedDescription);
    NSLog(@"Underlying Error: %@", [error.userInfo objectForKey:NSUnderlyingErrorKey]);

    switch ([error code]) {
        case RCNetworkError:
            showError(@"Network error, check your connection and try again.");
        case RCPurchaseNotAllowedError:
            showError(@"Purchases not allowed on this device.");
        case RCPurchaseInvalidError:
            showError(@"Purchase invalid, check payment source.");
        default:
            break;
    }

}

Android Errors

On Android, when an error has occurred the onError listener will receive a PurchasesError object.

When investigating or logging errors, reveiw the properties of PurchasesError:

  • code contains the PurchasesErrorCode that can be used for identifying the error.
  • message contains a description of the error. This description is meant for the developer.
  • underlyingErrorMessage contains a description of the underlying error that caused the error in question, if an underlying error is present.

Examples:

with(error) {
    // log error details
    print("Error: $code")
    print("Message: $message")
    print("Underlying Error: $underlyingErrorMessage")
    when (code) {
        PurchasesErrorCode.PurchaseNotAllowedError -> {
            showAlert("Purchases not allowed on this device.")
        }
        PurchasesErrorCode.PurchaseInvalidError -> {
            showAlert("Purchase invalid, check payment source.")
        }
        else -> {}
    }
}

Error codes common to all methods

Code
Meaning

NetworkError

❌ Indicates a network error occurred during the operation.


✅ Check network connectivity and retry the operation.

UnexpectedBackendResponseError

❌ Indicates the SDK received an unexpected response from the server.


Report the error with the full error object.

UnknownBackendError

❌ Indicates there was an unknown server error.


Report the error with the full error object.

StoreProblemError

❌ Indicates there was a problem connecting to the App Store or Play Store.


✅ Retry the operation.

OperationAlreadyInProgressError

❌ Indicates an identical operation is already in progress.


✅ Wait for the original operation to complete.

InvalidCredentialsError

❌ Indicates the application has been configured with an invalid API key.


✅ Ensure you're using the correct API Key from the RevenueCat dashboard and your Play Store Credentials / App Store Shared Secret are configured correctly.

InvalidAppUserIdError

❌ Indicates the App User Id is set to an invalid value.


✅ Make sure you're not sending an empty string as the user id.

UnknownError

❌ Indicates an unknown error occurred.


✅ Help us fix it.

Method specific error codes

Make Purchase

Code
Meaning

PurchaseCancelledError

❌ Indicates the user cancelled their purchase and were not charged.


✅ No action required.

ProductAlreadyPurchasedError

❌ Indicates this product is already active for the user.


✅ The device account already owns this product.

InvalidReceiptError

❌ Indicates the receipt is invalid.


✅ Receipt validation failed.

ProductNotAvailableForPurchaseError

❌ Indicates the product is not available for purchase by the device or user.


✅ Ensure you're attempting to purchase a product that's available for the device / user.

ReceiptAlreadyInUseError

❌ Indicates there is an identical receipt already in use by another subscriber.


✅ See allowSharingAppStoreAccount for details on handling.

MissingReceiptFileError

❌ Indicates there is no receipt file available on the device. This is common in sandbox testing.


✅ In Sandbox, make sure you make a purchase before attempting the operation.

PurchaseNotAllowedError

❌ Indicates the device or user is not allowed to make the purchase.


✅ The device / user is not allowed to make purchases.

PurchaseInvalidError

❌ Indicates one of the provided arguments was invalid, including the payment method.


✅ Ensure the device payment method is valid.

Restore Transactions

Code
Meaning

MissingReceiptFileError

❌ Indicates there is no receipt file available on the device. This is common in sandbox testing.


✅ In Sandbox, make sure you make a purchase before attempting the operation.

InvalidReceiptError

❌ Indicates the receipt is invalid.


✅ Receipt validation failed.

ReceiptAlreadyInUseError

❌ Indicates there is an identical receipt already in use by another subscriber.


✅ See allowSharingAppStoreAccount for details on handling.

Next Steps

Error Handling


Handling errors in Purchases SDK

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.