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

# Problemen met Whop-integraties oplossen

> Diagnosticeer en verhelp veelvoorkomende fouten in een Whop-integratie, van mislukte API-verzoeken tot ontbrekende webhooks.

Als er iets misgaat, zoek dan uit wat er faalt, controleer of je de juiste omgeving aanspreekt en bekijk de foutresponse. De meeste problemen komen neer op: verkeerde inloggegevens, een mismatch tussen sandbox en productie, een ontbrekende machtiging, of een webhookhandler die niet correct reageert.

## Snelle triage

| Symptoom | Eerste controle | Dieper ingaan |
| - | - | - |
| API-aanroepen retourneren `4xx` of `5xx` | Controleer de statuscode, de response-body, het endpoint en de omgeving. | [Fouten bij API-verzoeken](#api-request-errors) |
| API-aanroepen retourneren `401` | Controleer of de API-sleutel op de server aanwezig is en bij dezelfde omgeving hoort als de basis-URL van de API. | [API-authenticatie](#api-authentication) |
| API-aanroepen retourneren `403` | Controleer of de app, gebruiker of het account de vereiste machtiging voor de resource heeft. | [Machtigingen en scopes](#permissions-and-scopes) |
| OAuth stuurt terug met `error` | Lees `error` en `error_description` uit de callback-URL. | [OAuth-fouten](#oauth-errors) |
| Het Checkout-element laadt niet of de betaling mislukt | Koppel `onError`, inspecteer de variant of checkoutconfiguratie die je hebt doorgegeven en laat de koper het opnieuw proberen binnen het element. | [Checkoutfouten](#checkout-errors) |
| Webhooks komen niet aan of worden steeds opnieuw verstuurd | Controleer of het endpoint openbaar is, snel `2xx` retourneert vóór langlopend werk en de ruwe request-body gebruikt voor handtekeningverificatie. | [Aflevering van webhooks](#webhook-delivery) |
| Een Whop Element meldt `onError` | Log `message` en `code` en controleer daarna het toegangstoken en de opties die je hebt doorgegeven. | [Elementfouten](#element-errors) |

## Fouten bij API-verzoeken

Whop retourneert standaard HTTP-statuscodes. Als een verzoek mislukt, vertelt de response-body je waarom.

De meeste fouten bevatten een code en een bericht:

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

Sommige OAuth-endpoints retourneren in plaats daarvan de OAuth-standaardvelden `error` en `error_description`. Zie [OAuth-fouten](#oauth-errors) voor die gevallen.

| Status | Betekenis | Wat te doen |
| - | - | - |
| `400` | Het verzoek heeft een ongeldige vorm of mist een verplicht veld. | Controleer verplichte parameters, enumwaarden, ID's en de vorm van geneste objecten. |
| `401` | Het verzoek mist geldige authenticatie. | Controleer of de API-sleutel of het toegangstoken aanwezig en geldig is en vanaf je server wordt verstuurd. |
| `403` | De inloggegevens zijn geldig, maar kunnen de actie niet uitvoeren. | Controleer app-machtigingen, OAuth-scopes, accounteigendom en de subaccountcontext. |
| `404` | De resource of het endpoint is niet gevonden. | Controleer de route, de API-versie en het Whop-tag-ID, zoals `biz_`, `plan_`, `mem_` of `user_`. |
| `409` | Het verzoek conflicteert met de huidige status van de resource. | Haal de meest recente status van de resource op en probeer het alleen opnieuw als de actie nog van toepassing is. |
| `422` | Het verzoek is geldige JSON, maar slaagt niet voor de validatie. | Toon het validatiebericht aan de gebruiker zodat die de invoer kan corrigeren. |
| `429` | De client heeft te veel verzoeken in korte tijd verstuurd. | Voor `/api/v1`-verzoeken beperkt Whop geauthenticeerde API-aanroepen tot 600 verzoeken per minuut per operatie en per set API-inloggegevens. Wacht tot het retry-venster uit het foutbericht is verstreken. |
| `5xx` | Whop kon het verzoek niet voltooien. | Probeer idempotente operaties opnieuw met backoff en neem contact op met support als het probleem aanhoudt. |

### Rate limits

Voor `/api/v1`-verzoeken houdt Whop het aantal verzoeken bij per API-operatie en per set API-inloggegevens. De standaardlimiet is 600 verzoeken per minuut.

Als je de limiet overschrijdt, retourneert de API `429` met:

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

Wacht de vertraging uit het bericht af voordat je het opnieuw probeert. Probeer idempotente verzoeken opnieuw met exponentiële backoff. Probeer validatie-, authenticatie- of machtigingsfouten niet opnieuw zonder het verzoek aan te passen.

## API-authenticatie

Gebruik de inloggegevens die passen bij de plek waar de code draait.

| Inloggegevens | Gebruik ze wanneer | Veelgemaakte fout |
| - | - | - |
| Account API-sleutel | Je server handelt namens je eigen account. | De sleutel in browser-, mobiele of openbare clientcode zetten. |
| App API-sleutel | Je appserver handelt namens accounts die je app hebben geïnstalleerd. | Endpoints aanroepen voor een account dat de app niet heeft geïnstalleerd of geautoriseerd. |
| Account-scoped gebruikerstoken | De eigen gebruikers van je product bereiken Whop zonder in te loggen bij Whop. | `scoped_actions` weglaten, waardoor het token alle machtigingen erft van de API-sleutel die het heeft aangemaakt. |
| Account-toegangstoken | Een client heeft kortstondige toegang tot je account nodig zonder gekoppelde gebruiker. | Endpoints aanroepen die als gebruiker handelen; die weigeren het token. |
| OAuth-toegangstoken | Een ingelogde gebruiker geeft je app toegang tot diens account. | Een token met gebruikersscope behandelen als een accountbrede API-sleutel. |
| iframe-gebruikerstoken | Een Whop-app verifieert de gebruiker binnen een iframe-verzoek. | De handtekeningverificatie overslaan of het token doorsturen naar niet-gerelateerde clients. |

Als een API-verzoek mislukt:

1. Controleer of de omgeving bij de sleutel past: de SDK-omgeving `Production` (de standaard) voor productiesleutels en `Sandbox` voor sandboxsleutels, of `https://api.whop.com/api/v1` en `https://sandbox-api.whop.com/api/v1` als je de API rechtstreeks aanroept.
2. Controleer of ID's Whop-tagvoorvoegsels gebruiken zoals `biz_`, `user_`, `mem_`, `plan_`, `prod_`, `app_`, `pay_` of `ch_`, en geen interne numerieke ID's.
3. Log de HTTP-status, de response-body, het endpoint en het request-ID als Whop er een retourneert.
4. Probeer het alleen opnieuw als de fout tijdelijk is of door een rate limit komt. Probeer `401`, `403` of validatiefouten niet opnieuw zonder het verzoek aan te passen.

> [!WARNING]
>
> Stel Account API-sleutels of App API-sleutels nooit bloot in client-side code. Browser-, mobiele en iframe-code moet je server aanroepen, en je server moet Whop aanroepen.

## Machtigingen en scopes

Fouten `403` en `insufficient_scope` betekenen meestal dat de inloggegevens geldig zijn, maar die actie niet kunnen uitvoeren.

* Controleer voor Whop-apps of de app de vereiste machtigingen aanvraagt in [Machtigingen](https://docs.whop.com/nl/developer/guides/permissions.md), sla daarna de app-instellingen op en installeer of autoriseer opnieuw indien nodig.
* Vraag bij OAuth alleen de scopes aan die je functie nodig heeft en zorg dat de gebruiker de OAuth-flow heeft doorlopen nadat je die scopes hebt toegevoegd.
* Controleer bij API-sleutels die in het dashboard zijn aangemaakt of de sleutel hoort bij het account waarvan je het ID als `account_id` doorgeeft.
* Bepaal bij subaccounts of het bovenliggende of het onderliggende account eigenaar van de actie moet zijn, voordat je kiest welk account je doorgeeft.

## OAuth-fouten

OAuth-fouten retourneren een standaardpayload of een redirect-querystring met `error` en `error_description`.

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

| Fout | Betekenis | Oplossing |
| - | - | - |
| `invalid_request` | Een verplichte parameter ontbreekt of is onjuist opgemaakt. | Controleer `client_id`, `redirect_uri`, `response_type`, `code_challenge` en `code_challenge_method`. |
| `invalid_grant` | De autorisatiecode, het refreshtoken of het toegangstoken is verlopen, al gebruikt of door Whop ingetrokken. | Start de OAuth-flow opnieuw of vraag de gebruiker opnieuw in te loggen. Autorisatiecodes zijn eenmalig bruikbaar. |
| `invalid_client` | Whop herkent de app-client niet. | Controleer of je de juiste app en omgeving gebruikt. |
| `invalid_scope` | De aangevraagde scope is ongeldig of wordt niet herkend. | Controleer de beschikbare scopes in je app-instellingen en verwijder eventuele typfouten. |
| `insufficient_scope` | Het token bevat niet de scope die het endpoint vereist. | Voeg de scope toe in je app-instellingen en vraag opnieuw OAuth-toestemming. |
| `access_denied` | De gebruiker of het account heeft het autorisatieverzoek geweigerd. | De gebruiker heeft ervoor gekozen geen toegang te verlenen, of het account beperkt deze app. |
| `unsupported_response_type` | De parameter `response_type` wordt niet ondersteund. | Gebruik `response_type=code` voor de autorisatiecodeflow. |
| `unsupported_grant_type` | De parameter `grant_type` wordt niet ondersteund. | Gebruik `authorization_code` of `refresh_token`. |
| `rate_limit_exceeded` | Verzoeken voor OAuth-autorisatie, tokens of introspectie hebben een limiet over een kort tijdvenster bereikt. | Wacht even en respecteer de header `Retry-After` als die aanwezig is. |

> [!TIP]
>
> Redirect-URI's moeten exact overeenkomen. Als je `https://example.com/oauth/callback` hebt geconfigureerd, is `https://example.com/oauth/callback/` een andere URI.

## Checkoutfouten

Het Checkout-element en de iOS-checkout kunnen om verschillende redenen mislukken. Debug ze op dezelfde manier: controleer de variant of checkoutconfiguratie, inspecteer de foutcallback en bevestig de afhandeling op je server.

### Checkout-element

* Koppel `onError`. Die wordt uitgevoerd wanneer het element niet laadt of crasht, met een `message` en een `code` voor programmatische afhandeling.
* Als je de compatibiliteitseigenschap `plan` doorgeeft, controleer dan of de variant bestaat, actief is en hoort bij het account dat je verwacht.
* Als je `checkoutConfiguration` doorgeeft, controleer dan of je server die heeft aangemaakt en of je het `ch_`-ID ervan hebt doorgegeven.
* Elke optie wordt bij het aanmaken ingesteld. Wil je de bestelling wijzigen, mount dan een nieuwe checkout in plaats van `update()` aan te roepen.
* Een mislukte betaling opent dezelfde checkout opnieuw met de reden erbij, zodat de koper opnieuw kan betalen zonder opnieuw te mounten.
* Geef een `returnUrl` op voor een route die zowel succes- als retry-statussen kan weergeven. Een externe stap zoals 3DS of een bankpagina stuurt de koper daarheen terug.
* Gebruik webhooks voor de afhandeling. De redirect is nuttig voor de UI, maar je server moet vertrouwen op `payment.succeeded`.

### `iOS`-checkout

Handel verwachte en onverwachte fouten via verschillende paden af:

```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.")
}
```

## Aflevering van webhooks

Veelvoorkomende problemen met webhooks:

* **Geen event ontvangen**: controleer of de webhook-URL openbaar bereikbaar is, `https` gebruikt en bij het juiste account en de juiste omgeving hoort.
* **Handtekeningverificatie mislukt**: geef de ruwe request-body door aan `unwrapWebhook`. Parse geen JSON vóór de verificatie.
* **Er blijven retries plaatsvinden**: retourneer na de verificatie snel een `2xx`-response, voordat je langlopend werk in een achtergrondtaak start.
* **Dubbele afhandeling**: Whop levert webhooks minstens één keer af. Sla `webhook-id` of een andere event-identifier op en maak de handler idempotent.
* **Onverwachte volgorde**: ga er niet van uit dat events in chronologische volgorde binnenkomen. Haal de actuele status van de resource op als de volgorde ertoe doet.

Stuur voor lokale ontwikkeling met een tunnel een openbare URL door naar je machine en gebruik die URL in de webhookinstellingen van het dashboard.

## Elementfouten

Elk [Whop Element](https://docs.whop.com/nl/elements/latest/getting-started.md) accepteert een callback `onError`. Die wordt uitgevoerd wanneer het element niet laadt of crasht, en de waarde bevat een `message`, een optionele `code` voor programmatische afhandeling en een `sourceKey` wanneer een host-state-bron is mislukt.

Koppel hem altijd tijdens het ontwikkelen:

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

Als een element niet laadt:

1. Controleer of het toegangstoken is aangemaakt voor het account dat je verwacht en de scopes bevat die op de referentiepagina van het element staan.
2. Geef op je eigen domein altijd een `accessToken` door. De sessie van de kijker werkt alleen op whop.com.
3. Controleer of de container bestaat voordat je `mount` aanroept. React-componenten mounten zichzelf.
4. Luister naar `onReady` zodat je weet of het element is geïnitialiseerd.
5. Als het element in een onherstelbare status terechtkomt, roep dan `destroy()` aan en maak een nieuw element aan.

De [probleemoplossingstabel voor Elements](https://docs.whop.com/nl/elements/latest/getting-started.md#troubleshooting) somt de veelvoorkomende symptomen en hun oorzaken op.

## Sandbox en productie

Sandboxgegevens en productiegegevens zijn gescheiden.

| Omgeving | Dashboard | API |
| - | - | - |
| Sandbox | `https://sandbox.whop.com` | `https://sandbox-api.whop.com/api/v1` |
| Productie | `https://whop.com` | `https://api.whop.com/api/v1` |

Bij het overschakelen van sandbox naar productie:

* Maak nieuwe productie-API-sleutels aan.
* Wijzig de SDK-omgeving van `Sandbox` naar `Production`, of verwijder een sandbox-override met `baseUrl` / `base_url` / `WithBaseURL` uit 1.x.
* Maak producten, checkoutlinks, webhooks en subaccountrecords die alleen in de sandbox bestaan opnieuw aan in productie.
* Controleer of webhook-URL's naar productie-infrastructuur verwijzen en niet naar een lokale tunnel.

## Wat je meestuurt als je om hulp vraagt

Neem zo veel mogelijk van het volgende op:

* Het endpoint, de SDK-methode of de elementnaam die faalde.
* De omgeving: sandbox of productie.
* De statuscode, de foutbody, de OAuth-`error_description` of de `onError`-waarde van het element.
* De betrokken Whop-ID's, zonder geheimen.
* Het event-ID van de webhook of de header `webhook-id` bij webhookproblemen.
* Een kort codefragment dat laat zien hoe je de client, checkout, OAuth-URL, webhookhandler of het element aanmaakt.

> [card] [OAuth](https://docs.whop.com/nl/developer/guides/oauth.md)
>
> Bouw de OAuth 2.1 + PKCE-flow en handel het vernieuwen van tokens af.

> [card] [Webhooks](https://docs.whop.com/nl/developer/guides/webhooks.md)
>
> Verifieer handtekeningen voordat je events verwerkt, en handel retries af.

> [card] [Machtigingen](https://docs.whop.com/nl/developer/guides/permissions.md)
>
> Kies app-machtigingen en leg ze uit aan creators.

> [card] [Testen in de sandbox](https://docs.whop.com/nl/developer/guides/sandbox.md)
>
> Test API-aanroepen en checkoutflows zonder productie aan te raken.


## Related topics

- [GoHighLevel](https://docs.whop.com/nl/third-party-integrations/gohighlevel.md)
- [Whop-apps bouwen met React Native](https://docs.whop.com/nl/developer/guides/react-native.md)
- [Webhooks](https://docs.whop.com/nl/developer/guides/webhooks.md)
