Skip to main content
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

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:
Sommige OAuth-endpoints retourneren in plaats daarvan de OAuth-standaardvelden error en error_description. Zie OAuth-fouten voor die gevallen.

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:
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. 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.
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, 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.
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:

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 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:
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 somt de veelvoorkomende symptomen en hun oorzaken op.

Sandbox en productie

Sandboxgegevens en productiegegevens zijn gescheiden. 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.

OAuth

Bouw de OAuth 2.1 + PKCE-flow en handel het vernieuwen van tokens af.

Webhooks

Verifieer handtekeningen voordat je events verwerkt, en handel retries af.

Machtigingen

Kies app-machtigingen en leg ze uit aan creators.

Testen in de sandbox

Test API-aanroepen en checkoutflows zonder productie aan te raken.