Gestionar errores en el SDK de Flutter

Todos los errores que devuelve el SDK son de tipo AdaptyErrorCode. Aquí tienes un ejemplo:

Tip

Activa los logs detallados antes de depurar. La mayoría de los AdaptyError envuelven un error subyacente de StoreKit, Play Billing, red o backend. Con los logs detallados activados (await Adapty().setLogLevel(AdaptyLogLevel.verbose) — consulta Logging), ese error se imprime en la consola, lo que normalmente te indica la causa real.

Important

Si estas soluciones no resuelven tu problema, consulta Otros problemas para conocer los pasos a seguir antes de contactar con soporte, y así poder ayudarte de forma más eficiente.

    try {
      final result = await adapty.makePurchase(product: product);
    } on AdaptyError catch (adaptyError) {
      if (adaptyError.code == AdaptyErrorCode.paymentCancelled) {
        // Cancelled
      }
    } catch (e) {
    }

Códigos del sistema StoreKit

ErrorCódigoSolución
unknown0Código de error que indica que ocurrió un error desconocido o inesperado.
Vuelve a intentarlo o consulta la sección Otros problemas.
clientInvalid1Este código de error indica que el cliente no tiene permiso para realizar la acción intentada.
paymentCancelled2

Este código de error indica que el usuario canceló una solicitud de pago.

No se requiere ninguna acción, aunque a nivel de lógica de negocio puedes ofrecer un descuento al usuario o recordárselo más adelante.

paymentInvalid3Este error indica que uno de los parámetros de pago no fue reconocido por el App Store.
paymentNotAllowed4Este código de error indica que el usuario no tiene permiso para autorizar pagos.
storeProductNotAvailable5Este código de error indica que el producto solicitado no está disponible en el store.
Prueba a reinstalar la app.
cloudServicePermissionDenied6Este código de error indica que el usuario no ha permitido el acceso a la información del servicio en la nube.
cloudServiceNetworkConnectionFailed7Este código de error indica que el dispositivo no pudo conectarse a la red.
cloudServiceRevoked8Este código de error indica que el usuario ha revocado el permiso para usar este servicio en la nube.
privacyAcknowledgementRequired9Este código de error indica que el usuario aún no ha aceptado la política de privacidad de Apple.
unauthorizedRequestData10Este código de error indica que la app intenta usar una propiedad para la que no tiene el entitlement necesario.
invalidOfferIdentifier11

El identifier de la oferta no es válido. Por ejemplo, no has configurado ninguna oferta con ese identificador en el App Store, o has revocado la oferta.

Asegúrate de configurar las ofertas deseadas en AppStore Connect y de pasar un identificador de oferta válido.

invalidSignature12Este código de error indica que la firma en un descuento de pago no es válida.
missingOfferParams13Este código de error indica que faltan parámetros en un descuento de pago.
invalidOfferPrice14Este código de error indica que el precio que especificaste en App Store Connect ya no es válido. Las ofertas deben representar siempre un precio con descuento.

Códigos personalizados de Android

ErrorCodeSolution
adaptyNotInitialized20Debes configurar correctamente el SDK de Adapty mediante el método Adapty.activate. Aprende cómo hacerlo para Flutter.
productNotFound22Este error indica que el producto solicitado para la compra no está disponible en el store.
invalidJson23El JSON del paywall no es válido. Corrígelo en el Adapty Dashboard. Consulta el tema Personalizar el paywall con Remote Config para saber cómo solucionarlo.
currentSubscriptionToUpdateNotFoundInHistory24No se encuentra la suscripción original que debe renovarse.
pendingPurchase25Este error indica que el estado de la compra es pendiente en lugar de completado. Consulta la página Handling pending transactions en la documentación para desarrolladores de Android para más detalles.
billingServiceTimeout97Este error indica que la solicitud ha alcanzado el tiempo de espera máximo antes de que Google Play pueda responder. Esto puede deberse, por ejemplo, a un retraso en la ejecución de la acción solicitada por la llamada a la Play Billing Library.
featureNotSupported98La función solicitada no es compatible con el Play Store en el dispositivo actual.
billingServiceDisconnected99Este error fatal indica que la conexión de la app cliente al servicio de Google Play Store a través de BillingClient se ha interrumpido.
billingServiceUnavailable102Este error transitorio indica que el servicio de facturación de Google Play no está disponible en este momento. En la mayoría de los casos, significa que hay un problema de conexión de red entre el dispositivo cliente y los servicios de facturación de Google Play.
billingUnavailable103

Este error indica que se produjo un error de facturación del usuario durante el proceso de compra. Algunos casos en los que puede ocurrir:

1. La app del Play Store en el dispositivo del usuario está desactualizada.

2. El usuario se encuentra en un país no compatible.

3. El usuario es un empleado de una empresa y su administrador ha desactivado las compras para los usuarios.

4. Google Play no puede cargar el método de pago del usuario. Por ejemplo, la tarjeta de crédito del usuario puede haber expirado.

5. El usuario no ha iniciado sesión en la app del Play Store.

developerError105Este es un error fatal que indica que estás usando una API de forma incorrecta.
billingError106Este es un error fatal que indica un problema interno en el propio Google Play.
itemAlreadyOwned107El producto consumible ya ha sido comprado.
itemNotOwned108Este error indica que la acción solicitada sobre el artículo falló sin

Códigos StoreKit personalizados

ErrorCodeSolution
noProductIDsFound1000

Este error indica que ninguno de los productos que solicitaste en el paywall está disponible para compra en el App Store, aunque estén listados en él. A veces puede aparecer acompañado de una advertencia InvalidProductIdentifiers. Si la advertencia aparece sin error, ignórala.

Si encuentras este error, sigue los pasos de la sección Solución para el error noProductIDsFound con código 1000.

productRequestFailed1002No se pueden obtener los productos disponibles en este momento.
cantMakePayments1003Las compras in-app no están permitidas en este dispositivo. Consulta la guía de solución de problemas.
noPurchasesToRestore1004Obsoleto en Adapty Flutter SDK 4.0.4: restorePurchases() ya no devuelve este error. Cuando no hay nada que restaurar, el método se completa correctamente con el perfil actual, así que comprueba el estado del nivel de acceso en él. En versiones anteriores del SDK, este error indica que Google Play no encontró la compra a restaurar.
cantReadReceipt1005

No hay ningún recibo válido disponible en el dispositivo. Esto puede ser un problema durante las pruebas en sandbox.

En el sandbox no tendrás un archivo de recibo válido hasta que realices una compra, así que asegúrate de hacer una antes de acceder a él. Durante las pruebas en sandbox, verifica también que hayas iniciado sesión en el dispositivo con una cuenta sandbox de Apple válida.

productPurchaseFailed1006La compra del producto falló. Este error envuelve un error subyacente de StoreKit — lee el error interno (o activa los logs detallados para verlo en la consola) para conocer el motivo real. El error interno suele ser uno de los códigos de StoreKit del 0 al 14 de la tabla anterior; los más comunes son paymentCancelled, paymentInvalid, paymentNotAllowed o invalidOfferPrice. Si no puedes identificar un motivo concreto, prueba con un nuevo perfil sandbox; si sigue fallando, contacta con el soporte de Apple.
refreshReceiptFailed1010Este error indica que el recibo no fue recibido. Aplicable solo a StoreKit 1.
receiveRestoredTransactionsFailed1011La restauración de compras falló.
billingPlanUnavailable1060Solo iOS. El producto no ofrece el plan de facturación solicitado en este dispositivo o en esta tienda. Un plan de compromiso de 12 meses requiere iOS 26.4 o posterior y una app compilada con Xcode 26.5 o posterior. Requiere SDK 4.3.0 o posterior.

Códigos de red personalizados

ErrorCodeSolution
notActivated2002El SDK de Adapty no está activado.
Lo más habitual es que una pantalla de inicio o un hook de UI temprano llame a métodos de Adapty antes de que Adapty().activate devuelva el resultado. El síntoma es intermitente y puede no reproducirse en el emulador porque los tiempos en dispositivos reales son diferentes. Usa await con el Future de activate antes de programar cualquier otra llamada al SDK. Consulta Orden de llamadas en el SDK de Flutter para ver la secuencia completa.
badRequest2003Solicitud incorrecta.
Asegúrate de haber completado todos los pasos necesarios para integrarte con el App Store.
serverError2004Error del servidor.
Inténtalo de nuevo pasado un tiempo. Si el problema persiste, contacta con el equipo de soporte de Adapty.
networkFailed2005Este error indica problemas con la conexión de red en el dispositivo del usuario.
Prueba a desactivar la VPN o a cambiar de red móvil a WiFi o viceversa.
decodingFailed2006Este error indica que falló la decodificación de la respuesta.
Revisa tu código y asegúrate de que los parámetros que envías son válidos. Por ejemplo, este error puede indicar que estás usando una clave de API no válida.
encodingFailed2009Este error indica que falló la codificación de la solicitud.
analyticsDisabled3000No podemos procesar eventos de análisis porque los has desactivado.
wrongParam3001Este error indica que algunos de tus parámetros no son correctos.
Si estás usando el Paywall Builder de Adapty y no puedes mostrar un paywall por este error, activa Show on device en el Paywall Builder.
Otra posible causa del problema es que la versión del archivo de respaldo local no coincide con la versión del SDK. Descarga un nuevo archivo desde el dashboard.
activateOnceError3005No es posible llamar al método .activate más de una vez.
profileWasChanged3006El perfil de usuario cambió durante la operación.
Esto ocurre cuando se llama a un método mientras Adapty().identify todavía está en curso — la llamada en vuelo llega a un perfil que está a punto de ser reemplazado y el SDK la rechaza. Siempre usa await con identify antes de cualquier llamada de acción del usuario. Consulta Orden de llamadas en el SDK de Flutter.
unsupportedData3007Este error indica que el formato de datos no es compatible con el SDK.
fetchTimeoutError3101Este error indica que la operación de obtención superó el tiempo de espera.
operationInProgress3201Solo en iOS. En Unity, OperationInProgress. Hay otra operación del mismo tipo en ejecución.
Lo devuelve showStoreMessages cuando una llamada anterior sigue mostrando mensajes del store: consulta Flutter, React Native o Unity. Espera a que finalice y vuelve a intentarlo. Requiere SDK 4.3.0 o posterior.
resolverFailure3202Solo en iOS. En Unity, ResolverFailure. El SDK no pudo encontrar el recurso que necesita la operación.
Lo devuelve showStoreMessages cuando no existe ninguna escena de ventana activa en primer plano. Llama al método de nuevo cuando la app esté en primer plano. Requiere SDK 4.3.0 o posterior.

Código de interfaz personalizado y códigos de plugins

ErrorCódigoSolución
jsException4105Se lanzó una excepción desde JavaScript mientras se ejecutaba un paywall u onboarding creado en el builder. Activa el registro detallado para ver el error de JavaScript subyacente.
operationInterrupted9000Esta operación fue interrumpida por el sistema.
Vuelve a intentar la llamada.
emptyResult10001El plugin de Flutter recibió un resultado vacío del SDK nativo.
Vuelve a intentar la llamada y consulta la sección Otros problemas.
internalPluginError10002Se produjo un error interno en el plugin de Flutter.
Consulta la sección Otros problemas.

Otros problemas

Si aún no has encontrado una solución, los siguientes pasos pueden ser:

  • Actualizar el SDK a la última versión: Siempre recomendamos actualizar a las últimas versiones del SDK, ya que son más estables e incluyen correcciones para problemas conocidos.
  • Contacta con el equipo de soporte u obtén ayuda de otros desarrolladores en el foro de soporte.
  • Contacta con el equipo de soporte a través de support@adapty.io o mediante el chat: Si no estás listo para actualizar el SDK o no ha funcionado, contacta con nuestro equipo de soporte. Ten en cuenta que tu problema se resolverá más rápido si activas el registro detallado y compartes los registros con el equipo. También puedes adjuntar fragmentos de código relevantes.