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: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:
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:
- Confirma que el entorno coincide con la clave: el entorno
Productiondel SDK (el predeterminado) para claves de producción ySandboxpara claves de sandbox, ohttps://api.whop.com/api/v1yhttps://sandbox-api.whop.com/api/v1cuando llamas a la API directamente. - Confirma que los ID usan prefijos de etiqueta de Whop como
biz_,user_,mem_,plan_,prod_,app_,pay_och_, y no ID numéricos internos. - Registra el estado HTTP, el cuerpo de la respuesta, el endpoint y el ID de la solicitud si Whop devuelve uno.
- Reintenta solo cuando el error sea transitorio o se deba al límite de solicitudes. No reintentes errores
401,403ni de validación sin cambiar la solicitud.
Permisos y scopes
Los errores403 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 conerror y error_description.
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 unmessagey uncodepara 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 IDch_. - 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
returnUrlen 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
httpsy 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
2xxrá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-idu 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.
Errores de elementos
Todos los Whop Element aceptan un callbackonError. 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:
- 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.
- En tu propio dominio, pasa siempre un
accessToken. La sesión del espectador solo funciona en whop.com. - Confirma que el contenedor existe antes de llamar a
mount. Los componentes de React se montan solos. - Escucha
onReadypara saber si el elemento se inicializó. - Si el elemento entra en un estado irrecuperable, llama a
destroy()y crea uno nuevo.
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
SandboxaProduction, o elimina una anulación de sandbox de 1.x conbaseUrl/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_descriptionde OAuth o el valor deonErrordel elemento. - Los ID de Whop implicados, sin secretos.
- El ID del evento del webhook o el encabezado
webhook-iden 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.

