Gestionar errores en el SDK de Capacitor

Cada error que devuelve el SDK es una instancia de AdaptyError. Aquí tienes un ejemplo:

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 (adapty.setLogLevel({ logLevel: 'verbose' }) — consulta Logging), ese error se muestra en la consola, lo que generalmente indica la causa real. La propiedad detail de AdaptyError se rellena independientemente del nivel de log — los logs detallados simplemente la muestran en la consola.


try {
  const result = await adapty.makePurchase({ product });
  
  // Manejar el resultado de la compra
  if (result.type === 'success') {
    console.log('Compra exitosa:', result.profile);
  } else if (result.type === 'user_cancelled') {
    console.log('El usuario canceló la compra');
  } else if (result.type === 'pending') {
    console.log('La compra está pendiente');
  }
} catch (error) {
  if (error instanceof AdaptyError) {
    console.error('Error de Adapty:', error.adaptyCode, error.localizedDescription);
    
    // Manejar códigos de error específicos
    switch (error.adaptyCode) {
      case ErrorCodeName.cantMakePayments:
        console.log('Las compras in-app no están permitidas en este dispositivo');
        break;
      case ErrorCodeName.notActivated:
        console.log('El SDK de Adapty no está activado');
        break;
      case ErrorCodeName.productPurchaseFailed:
        console.log('La compra falló:', error.detail);
        break;
      default:
        console.log('Se produjo otro error:', error.detail);
    }
  } else {
    console.error('Error no relacionado con Adapty:', error);
  }
}

Propiedades del error

La clase AdaptyError expone las siguientes propiedades:

PropiedadTipoDescripción
adaptyCodenumberCódigo de error numérico (p. ej., 1003 para cantMakePayments)
localizedDescriptionstringMensaje de error legible por el usuario
detailstring | undefinedDetalles adicionales del error (opcional)
messagestringMensaje de error completo con código y descripción

Códigos de error

El SDK exporta constantes y utilidades para trabajar con códigos de error:

Constante ErrorCodeName

Mapea identificadores de cadena a códigos numéricos:


ErrorCodeName.cantMakePayments // 1003
ErrorCodeName.notActivated // 2002
ErrorCodeName.networkFailed // 2005

Constante ErrorCode

Mapea códigos numéricos a identificadores de cadena:


ErrorCode[1003] // 'cantMakePayments'
ErrorCode[2002] // 'notActivated'
ErrorCode[2005] // 'networkFailed'

Funciones de ayuda


// Get numeric code from string name:
getErrorCode('cantMakePayments') // 1003

// Get string name from numeric code:
getErrorPrompt(1003) // 'cantMakePayments'

Comparar códigos de error

Importante: error.adaptyCode es un número, así que compáralo directamente con códigos numéricos:

// Option 1: Use ErrorCodeName constant (recommended) ✅
if (error.adaptyCode === ErrorCodeName.cantMakePayments) {
  console.log('Cannot make payments');
}

// Option 2: Compare with numeric literal ✅
if (error.adaptyCode === 1003) {
  console.log('Cannot make payments');
}

// NOT like this ❌ - compares number to string and will never match
if (error.adaptyCode === ErrorCode[1003]) {
}

Manejador de errores global

Puedes configurar un manejador de errores global para capturar todos los errores de Adapty:


// Configura el manejador de errores global
AdaptyError.onError = (error: AdaptyError) => {
  console.error('Error global de Adapty:', {
    code: error.adaptyCode,
    message: error.localizedDescription,
    detail: error.detail
  });
  
  // Gestiona tipos de error específicos de forma global
  if (error.adaptyCode === ErrorCodeName.notActivated) {
    // SDK no activado - puede que sea necesario reintentar la activación
    console.log('SDK no activado, intentando reactivar...');
  }
};

Patrones comunes de manejo de errores

Gestión de errores en las compras


async function handlePurchase(product: AdaptyPaywallProduct) {
  try {
    const result = await adapty.makePurchase({ product });
    
    if (result.type === 'success') {
      console.log('Compra exitosa:', result.profile);
    } else if (result.type === 'user_cancelled') {
      console.log('El usuario canceló la compra');
    } else if (result.type === 'pending') {
      console.log('La compra está pendiente');
    }
  } catch (error) {
    if (error instanceof AdaptyError) {
      switch (error.adaptyCode) {
        case ErrorCodeName.cantMakePayments:
          console.log('Las compras in-app no están permitidas');
          break;
        case ErrorCodeName.productPurchaseFailed:
          console.log('La compra falló:', error.detail);
          break;
        default:
          console.error('Error en la compra:', error.localizedDescription);
      }
    }
  }
}

Gestión de errores de red


async function fetchPaywall(placementId: string) {
  try {
    const paywall = await adapty.getPaywall({ placementId });
    return paywall;
  } catch (error) {
    if (error instanceof AdaptyError) {
      switch (error.adaptyCode) {
        case ErrorCodeName.networkFailed:
          console.log('Network error, retrying...');
          // Implement retry logic
          break;
        case ErrorCodeName.serverError:
          console.log('Server error:', error.detail);
          break;
        case ErrorCodeName.notActivated:
          console.log('SDK not activated');
          break;
        default:
          console.error('Paywall fetch error:', error.localizedDescription);
      }
    }
    throw error;
  }
}

Códigos de sistema de StoreKit

ErrorCódigoDescripción
unknown0Este error indica que ocurrió un error desconocido o inesperado.
clientInvalid1Este código de error indica que el cliente no tiene permiso para realizar la acción solicitada.
paymentCancelled2

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

No se requiere ninguna acción, pero en términos 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 la store.
paymentNotAllowed4

Este código de error indica que el usuario no tiene permiso para autorizar pagos. Posibles razones:

- Los pagos no están disponibles en el país del usuario.

- El usuario es menor de edad.

storeProductNotAvailable5Este código de error indica que el producto solicitado no está disponible en la App Store. Asegúrate de que el producto esté disponible en el país correspondiente.
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 la store.
unauthorizedRequestData10Este código de error indica que la solicitud está construida de forma incorrecta.
invalidOfferIdentifier11

El identificador de oferta no es válido. Posibles razones:

- No has configurado una oferta con ese identificador en la App Store.

- Has revocado la oferta.

- Hay un error tipográfico en el ID de la oferta.

invalidSignature12Este código de error indica que la firma en un descuento de pago no es válida. Asegúrate de haber rellenado el campo In-app purchase Key ID y de haber subido el archivo In-App Purchase Private Key. Consulta el tema Configure App Store integration para más detalles.
missingOfferParams13

Este error indica problemas con la integración de Adapty o con las ofertas.

Consulta Configure App Store integration y Offers para más detalles sobre cómo configurarlas.

invalidOfferPrice14Este código de error indica que el precio que especificaste en la store ya no es válido. Las ofertas siempre deben representar un precio con descuento.

Códigos personalizados de Android

ErrorCódigoDescripción
adaptyNotInitialized20Necesitas configurar correctamente el SDK de Adapty mediante el método Adapty.activate. Aprende cómo hacerlo para React Native.
productNotFound22Este error indica que el producto solicitado para la compra no está disponible en la store.
invalidJson23El JSON del paywall no es válido. Corrígelo en el Adapty Dashboard. Consulta el tema Customize paywall with remote config para más detalles sobre cómo corregirlo.
currentSubscriptionToUpdateNotFoundInHistory24No se encontró la suscripción original que debe renovarse.
pendingPurchase25Este error indica que el estado de la compra está 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 alcanzó el tiempo de espera máximo antes de que Google Play pudiera 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 la 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 del 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 ocurrió un error de facturación del usuario durante el proceso de compra. Algunos ejemplos de cuándo puede ocurrir:

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

2. El usuario está en un país no compatible.

3. El usuario es un empleado de empresa y su administrador ha deshabilitado las compras.

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

5. El usuario no ha iniciado sesión en la app de 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 Google Play.
itemAlreadyOwned107El producto consumible ya ha sido comprado.
itemNotOwned108Este error indica que la acción solicitada sobre el artículo falló.

Códigos personalizados de StoreKit

ErrorCódigoDescripción
noProductIDsFound1000

Este error indica que ninguno de los productos del paywall está disponible en la store.

Si encuentras este error, sigue los pasos a continuación para resolverlo:

1. Comprueba que todos los productos se han añadido al Adapty Dashboard.

2. Asegúrate de que el Bundle ID de tu app coincide con el de Apple Connect.

3. Verifica que los identificadores de producto de las app stores coincidan con los que has añadido al Dashboard. Ten en cuenta que los identificadores no deben contener el Bundle ID, a menos que ya esté incluido en la store.

4. Confirma que el estado de pago de la app está activo en tu configuración fiscal de Apple. Asegúrate de que tu información fiscal está actualizada y que tus certificados son válidos.

5. Comprueba que hay una cuenta bancaria vinculada a la app para que pueda ser elegible para la monetización.

6. Verifica que los productos estén disponibles en todas las regiones. Además, asegúrate de que tus productos estén en estado “Ready to Submit”.

productRequestFailed1002

No se pueden obtener los productos disponibles en este momento. Posible razón:

- Aún no se ha creado ninguna caché y no hay conexión a internet al mismo tiempo.

cantMakePayments1003Las compras in-app no están permitidas en este dispositivo.
noPurchasesToRestore1004Este error indica que Google Play no encontró ninguna compra que restaurar.
cantReadReceipt1005

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

No se requiere ninguna acción, pero en términos de lógica de negocio, puedes ofrecer un descuento al usuario o recordárselo más adelante.

productPurchaseFailed1006La compra del producto falló. Esto envuelve un error subyacente de StoreKit: lee el error interno (o activa los registros detallados para verlo en la consola) para conocer la razón exacta. El error interno suele ser uno de los códigos de StoreKit 0–14 de la tabla anterior, siendo los más comunes paymentCancelled, paymentInvalid, paymentNotAllowed o invalidOfferPrice. Si no puedes identificar una razón concreta, prueba con un nuevo perfil de sandbox; si sigue fallando, contacta con el soporte de Apple.
refreshReceiptFailed1010Este error indica que no se recibió el recibo. Solo aplica a StoreKit 1.
receiveRestoredTransactionsFailed1011La restauración de la compra falló.

Códigos de red personalizados

ErrorCódigoDescripción
notActivated2002Necesitas configurar correctamente el SDK de Adapty mediante el método Adapty.activate. Aprende cómo hacerlo para React Native.
badRequest2003Solicitud incorrecta.
serverError2004Error del servidor.
networkFailed2005La solicitud de red falló.
decodingFailed2006Este error indica que falló la decodificación de la respuesta.
encodingFailed2009Este error indica que falló la codificación de la solicitud.
analyticsDisabled3000No podemos gestionar eventos de análisis porque los has desactivado. Consulta el tema Analytics integration para más detalles.
wrongParam3001Este error indica que alguno de tus parámetros no es correcto: está en blanco cuando no puede estarlo, tiene un tipo incorrecto, etc.
activateOnceError3005No es posible llamar al método .activate más de una vez.
profileWasChanged3006El perfil de usuario cambió durante la operación.
fetchTimeoutError3101Este error significa que el paywall no se pudo obtener dentro del límite establecido. Para evitar esta situación, configura los fallbacks locales.
operationInterrupted9000Esta operación fue interrumpida por el sistema.