Skip to main content
Cuando algo falla, averigua qué está fallando, comprueba que estás usando el entorno correcto y revisa la respuesta de error. La mayoría de los problemas se reducen a: una credencial incorrecta, una confusión entre sandbox y producción, un permiso que falta o un manejador de webhooks que no responde correctamente.

Diagnóstico rápido

Errores de solicitudes a la API

Whop devuelve códigos de estado HTTP estándar. Cuando una solicitud falla, el cuerpo de la respuesta te indica el motivo. La mayoría de los errores incluyen un código y un mensaje:
Algunos endpoints de OAuth devuelven en su lugar los campos estándar de OAuth error y error_description. Consulta Errores de OAuth para esos casos.

Límites de solicitudes

Para las solicitudes a /api/v1, Whop controla el volumen de solicitudes por operación de la API y por credencial de API. El límite predeterminado es de 600 solicitudes por minuto. Cuando superas el límite, la API devuelve 429 con:
Espera el tiempo indicado en el mensaje antes de reintentar. En las solicitudes idempotentes, reintenta con backoff exponencial. No reintentes errores de validación, autenticación o permisos sin cambiar la solicitud.

Autenticación de la API

Usa la credencial que corresponda al lugar donde se ejecuta el código. Si una solicitud a la API falla:
  1. Confirma que el entorno coincide con la clave: el entorno Production del SDK (el predeterminado) para claves de producción y Sandbox para claves de sandbox, o https://api.whop.com/api/v1 y https://sandbox-api.whop.com/api/v1 cuando llamas a la API directamente.
  2. Confirma que los ID usan prefijos de etiqueta de Whop como biz_, user_, mem_, plan_, prod_, app_, pay_ o ch_, y no ID numéricos internos.
  3. Registra el estado HTTP, el cuerpo de la respuesta, el endpoint y el ID de la solicitud si Whop devuelve uno.
  4. Reintenta solo cuando el error sea transitorio o se deba al límite de solicitudes. No reintentes errores 401, 403 ni de validación sin cambiar la solicitud.
Nunca expongas claves de API de Account ni claves de API de app en código del lado del cliente. El código del navegador, de móvil y de iframes debe llamar a tu servidor, y tu servidor debe llamar a Whop.

Permisos y scopes

Los errores 403 e insufficient_scope suelen significar que la credencial es válida, pero no puede realizar esa acción.
  • Para las apps de Whop, confirma que la app solicita los permisos necesarios en Permisos, guarda los ajustes de la app y vuelve a instalarla o autorizarla cuando sea necesario.
  • Para OAuth, solicita solo los scopes que necesita tu funcionalidad y asegúrate de que el usuario completó el flujo de OAuth después de que añadieras esos scopes.
  • Para las claves de API creadas en el panel, confirma que la clave pertenece a la cuenta cuyo ID pasas como account_id.
  • Para las subcuentas, confirma si la acción debe pertenecer a la cuenta principal o a la secundaria antes de elegir la cuenta que pasas.

Errores de OAuth

Los errores de OAuth devuelven un payload estándar o una cadena de consulta de redirección con error y error_description.
Las URI de redirección deben coincidir exactamente. Si configuraste https://example.com/oauth/callback, https://example.com/oauth/callback/ es una URI diferente.

Errores de checkout

El elemento Checkout y el checkout de iOS pueden fallar por motivos diferentes. Depúralos de la misma manera: revisa la variante o la configuración de checkout, inspecciona el callback de error y confirma el cumplimiento del pedido en tu servidor.

Elemento Checkout

  • Adjunta onError. Se ejecuta cuando el elemento no carga o falla, con un message y un code para gestionarlo mediante código.
  • Si pasas la propiedad de compatibilidad plan, confirma que la variante existe, está activa y pertenece a la cuenta que esperas.
  • Si pasas checkoutConfiguration, confirma que tu servidor la creó y que pasaste su ID ch_.
  • Todas las opciones se establecen al crearlo. Para cambiar el pedido, monta un nuevo checkout en lugar de llamar a update().
  • Un pago fallido vuelve a abrir el mismo checkout mostrando el motivo, para que el comprador pueda pagar de nuevo sin volver a montarlo.
  • Proporciona una returnUrl en una ruta que pueda mostrar los estados de éxito y de reintento. Un paso externo, como 3DS o la página de un banco, devuelve al comprador ahí.
  • Usa webhooks para el cumplimiento del pedido. La redirección es útil para la interfaz, pero tu servidor debe basarse en payment.succeeded.

Checkout de iOS

Gestiona los fallos esperados y los inesperados con rutas diferentes:

Entrega de webhooks

Problemas comunes con los webhooks:
  • No se recibe ningún evento: confirma que la URL del webhook es accesible públicamente, usa https y pertenece a la cuenta y al entorno correctos.
  • La verificación de la firma falla: pasa el cuerpo sin procesar de la solicitud a unwrapWebhook. No analices el JSON antes de la verificación.
  • Los reintentos no paran: devuelve una respuesta 2xx rápidamente después de la verificación, antes de iniciar trabajos largos en un job en segundo plano.
  • Cumplimiento duplicado: Whop entrega los webhooks al menos una vez. Guarda webhook-id u otro identificador del evento y haz que el manejador sea idempotente.
  • Orden inesperado: no des por hecho que los eventos llegan en orden cronológico. Obtén el estado actual del recurso cuando el orden importe.
Para el desarrollo local, reenvía una URL pública a tu máquina con un túnel y usa esa URL en los ajustes de webhooks del panel.

Errores de elementos

Todos los Whop Element aceptan un callback onError. Se ejecuta cuando el elemento no carga o falla, y el valor incluye un message, un code opcional para gestionarlo mediante código y un sourceKey cuando falló una fuente de estado del host. Adjúntalo siempre mientras desarrollas:
Si un elemento no carga:
  1. Confirma que el token de acceso se generó para la cuenta que esperas y que incluye los scopes que indica la página de referencia del elemento.
  2. En tu propio dominio, pasa siempre un accessToken. La sesión del espectador solo funciona en whop.com.
  3. Confirma que el contenedor existe antes de llamar a mount. Los componentes de React se montan solos.
  4. Escucha onReady para saber si el elemento se inicializó.
  5. Si el elemento entra en un estado irrecuperable, llama a destroy() y crea uno nuevo.
La tabla de solución de problemas de Elements enumera los síntomas comunes y sus causas.

Sandbox y producción

Los datos del sandbox y los de producción están separados. Al pasar del sandbox a producción:
  • Crea nuevas claves de API de producción.
  • Cambia el entorno del SDK de Sandbox a Production, o elimina una anulación de sandbox de 1.x con baseUrl / base_url / WithBaseURL.
  • Vuelve a crear en producción los productos, enlaces de checkout, webhooks y registros de subcuentas que solo existen en el sandbox.
  • Confirma que las URL de los webhooks apuntan a la infraestructura de producción, no a un túnel local.

Qué incluir al pedir ayuda

Incluye todo lo posible de lo siguiente:
  • El endpoint, el método del SDK o el nombre del elemento que falló.
  • El entorno: sandbox o producción.
  • El código de estado, el cuerpo del error, el error_description de OAuth o el valor de onError del elemento.
  • Los ID de Whop implicados, sin secretos.
  • El ID del evento del webhook o el encabezado webhook-id en los problemas de webhooks.
  • Un fragmento de código breve que muestre cómo creas el cliente, el checkout, la URL de OAuth, el manejador de webhooks o el elemento.

OAuth

Crea el flujo OAuth 2.1 + PKCE y gestiona la actualización de tokens.

Webhooks

Verifica las firmas antes de procesar eventos y gestiona los reintentos.

Permisos

Elige los permisos de la app y explícaselos a los creadores.

Prueba en el sandbox

Prueba llamadas a la API y flujos de checkout sin tocar producción.