> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Solución de problemas de integraciones con Whop

> Diagnostica y corrige errores comunes en una integración con Whop, desde solicitudes a la API fallidas hasta webhooks que no llegan.

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

| Síntoma | Primera comprobación | Más información |
| - | - | - |
| Las llamadas a la API devuelven `4xx` o `5xx` | Revisa el código de estado, el cuerpo de la respuesta, el endpoint y el entorno. | [Errores de solicitudes a la API](#api-request-errors) |
| Las llamadas a la API devuelven `401` | Confirma que la clave de API está presente en el servidor y pertenece al mismo entorno que la URL base de la API. | [Autenticación de la API](#api-authentication) |
| Las llamadas a la API devuelven `403` | Comprueba que la app, el usuario o la cuenta tiene el permiso necesario para el recurso. | [Permisos y scopes](#permissions-and-scopes) |
| OAuth redirige de vuelta con `error` | Lee `error` y `error_description` de la URL de callback. | [Errores de OAuth](#oauth-errors) |
| El elemento Checkout no carga o el pago falla | Adjunta `onError`, revisa la variante o la configuración de checkout que pasaste y deja que el comprador vuelva a intentarlo dentro del elemento. | [Errores de checkout](#checkout-errors) |
| Los webhooks no llegan o se reintentan continuamente | Verifica que el endpoint sea público, que devuelva `2xx` rápidamente antes de cualquier trabajo largo y que use el cuerpo sin procesar de la solicitud para verificar la firma. | [Entrega de webhooks](#webhook-delivery) |
| Un Whop Element informa `onError` | Registra `message` y `code`, y después confirma el token de acceso y las opciones que pasaste. | [Errores de elementos](#element-errors) |

## 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:

```json theme={null}
{
	"error": {
		"code": "invalid_request",
		"message": "Missing required parameter: account_id"
	}
}
```

Algunos endpoints de OAuth devuelven en su lugar los campos estándar de OAuth `error` y `error_description`. Consulta [Errores de OAuth](#oauth-errors) para esos casos.

| Estado | Significado | Qué hacer |
| - | - | - |
| `400` | La solicitud tiene una forma no válida o le falta un campo obligatorio. | Revisa los parámetros obligatorios, los valores de enum, los ID y la forma de los objetos anidados. |
| `401` | A la solicitud le falta una autenticación válida. | Confirma que la clave de API o el token de acceso está presente, es válido y se envía desde tu servidor. |
| `403` | La credencial es válida, pero no puede realizar la acción. | Revisa los permisos de la app, los scopes de OAuth, la propiedad de la cuenta y el contexto de la subcuenta. |
| `404` | No se encontró el recurso o el endpoint. | Confirma la ruta, la versión de la API y el ID con etiqueta de Whop, como `biz_`, `plan_`, `mem_` o `user_`. |
| `409` | La solicitud entra en conflicto con el estado actual del recurso. | Obtén el estado más reciente del recurso y vuelve a intentarlo solo si la acción sigue siendo aplicable. |
| `422` | La solicitud es JSON válido, pero no supera la validación. | Muestra el mensaje de validación al usuario para que pueda corregir sus datos. |
| `429` | El cliente envió demasiadas solicitudes en un intervalo corto. | Para las solicitudes a `/api/v1`, Whop limita las llamadas autenticadas a la API a 600 solicitudes por minuto por operación y credencial de API. Espera hasta que haya pasado el intervalo de reintento indicado en el mensaje de error. |
| `5xx` | Whop no pudo completar la solicitud. | Reintenta con backoff en las operaciones idempotentes y contacta con soporte si persiste. |

### 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:

```json theme={null}
{
	"error": {
		"type": "rate_limit_exceeded",
		"message": "Try again in 12 seconds."
	}
}
```

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.

| Credencial | Úsala cuando | Error común |
| - | - | - |
| Clave de API de Account | Tu servidor actúa en nombre de tu propia cuenta. | Poner la clave en código del navegador, móvil o de cliente público. |
| Clave de API de app | El servidor de tu app actúa en nombre de las cuentas que instalaron tu app. | Llamar a endpoints de una cuenta que no ha instalado ni autorizado la app. |
| Token de usuario con alcance de cuenta | Los propios usuarios de tu producto acceden a Whop sin iniciar sesión en Whop. | Omitir `scoped_actions`, de modo que el token hereda todos los permisos de la clave de API que lo generó. |
| Token de acceso de cuenta | Un cliente necesita acceso de corta duración a tu cuenta sin un usuario asociado. | Llamar a endpoints que actúan como un usuario, que lo rechazan. |
| Token de acceso de OAuth | Un usuario que ha iniciado sesión concede a tu app acceso a su cuenta. | Tratar un token con alcance de usuario como una clave de API para toda la cuenta. |
| Token de usuario de iframe | Una app de Whop verifica al usuario dentro de una solicitud de iframe. | Omitir la verificación de la firma o reenviar el token a clientes no relacionados. |

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.

> [!WARNING]
>
> 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](https://docs.whop.com/es/developer/guides/permissions.md), 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`.

```json theme={null}
{
	"error": "invalid_grant",
	"error_description": "Authorization code has expired"
}
```

| Error | Significado | Solución |
| - | - | - |
| `invalid_request` | Falta un parámetro obligatorio o tiene un formato incorrecto. | Revisa `client_id`, `redirect_uri`, `response_type`, `code_challenge` y `code_challenge_method`. |
| `invalid_grant` | El código de autorización, el token de actualización o el token de acceso ha caducado, ya se usó o Whop lo revocó. | Reinicia el flujo de OAuth o pide al usuario que vuelva a iniciar sesión. Los códigos de autorización son de un solo uso. |
| `invalid_client` | Whop no reconoce el cliente de la app. | Confirma que estás usando la app y el entorno correctos. |
| `invalid_scope` | El scope solicitado no es válido o no se reconoce. | Revisa los scopes disponibles en los ajustes de tu app y elimina cualquier errata. |
| `insufficient_scope` | El token no incluye el scope que requiere el endpoint. | Añade el scope en los ajustes de tu app y vuelve a ejecutar el consentimiento de OAuth. |
| `access_denied` | El usuario o la cuenta denegó la solicitud de autorización. | El usuario decidió no conceder acceso, o la cuenta restringe esta app. |
| `unsupported_response_type` | El parámetro `response_type` no es compatible. | Usa `response_type=code` para el flujo de código de autorización. |
| `unsupported_grant_type` | El parámetro `grant_type` no es compatible. | Usa `authorization_code` o `refresh_token`. |
| `rate_limit_exceeded` | Las solicitudes de autorización, token o introspección de OAuth alcanzaron un límite de intervalo corto. | Espera y respeta el encabezado `Retry-After` si está presente. |

> [!TIP]
>
> 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:

```swift theme={null}
do {
    let result = try await checkout.purchase(planId)
    print("Receipt ID: \(result.receiptId)")
} catch WhopCheckoutError.notConfigured {
    // SDK was not set up. Call WhopCheckout.configure() first.
} catch WhopCheckoutError.cancelled {
    // The user dismissed checkout. This is not a payment failure.
} catch WhopCheckoutError.paymentFailed(let message) {
    showError(message)
} catch {
    showError("Something went wrong. Please try again.")
}
```

## 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](https://docs.whop.com/es/elements/latest/getting-started.md) 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:

```tsx theme={null}
<CheckoutElement
	onError={(error) => {
		console.error("CheckoutElement failed", error.code, error.message);
	}}
/>
```

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](https://docs.whop.com/es/elements/latest/getting-started.md#troubleshooting) enumera los síntomas comunes y sus causas.

## Sandbox y producción

Los datos del sandbox y los de producción están separados.

| Entorno | Panel | API |
| - | - | - |
| Sandbox | `https://sandbox.whop.com` | `https://sandbox-api.whop.com/api/v1` |
| Producción | `https://whop.com` | `https://api.whop.com/api/v1` |

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.

> [card] [OAuth](https://docs.whop.com/es/developer/guides/oauth.md)
>
> Crea el flujo OAuth 2.1 + PKCE y gestiona la actualización de tokens.

> [card] [Webhooks](https://docs.whop.com/es/developer/guides/webhooks.md)
>
> Verifica las firmas antes de procesar eventos y gestiona los reintentos.

> [card] [Permisos](https://docs.whop.com/es/developer/guides/permissions.md)
>
> Elige los permisos de la app y explícaselos a los creadores.

> [card] [Prueba en el sandbox](https://docs.whop.com/es/developer/guides/sandbox.md)
>
> Prueba llamadas a la API y flujos de checkout sin tocar producción.


## Related topics

- [Crea apps de Whop con React Native](https://docs.whop.com/es/developer/guides/react-native.md)
- [GoHighLevel](https://docs.whop.com/es/third-party-integrations/gohighlevel.md)
- [Primeros pasos con Elements](https://docs.whop.com/es/elements/latest/getting-started.md)
