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: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:
API-authenticatie
Gebruik de inloggegevens die passen bij de plek waar de code draait.
Als een API-verzoek mislukt:
- Controleer of de omgeving bij de sleutel past: de SDK-omgeving
Production(de standaard) voor productiesleutels enSandboxvoor sandboxsleutels, ofhttps://api.whop.com/api/v1enhttps://sandbox-api.whop.com/api/v1als je de API rechtstreeks aanroept. - Controleer of ID’s Whop-tagvoorvoegsels gebruiken zoals
biz_,user_,mem_,plan_,prod_,app_,pay_ofch_, en geen interne numerieke ID’s. - Log de HTTP-status, de response-body, het endpoint en het request-ID als Whop er een retourneert.
- Probeer het alleen opnieuw als de fout tijdelijk is of door een rate limit komt. Probeer
401,403of validatiefouten niet opnieuw zonder het verzoek aan te passen.
Machtigingen en scopes
Fouten403 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_iddoorgeeft. - 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 meterror en error_description.
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 eenmessageen eencodevoor programmatische afhandeling. - Als je de compatibiliteitseigenschap
plandoorgeeft, controleer dan of de variant bestaat, actief is en hoort bij het account dat je verwacht. - Als je
checkoutConfigurationdoorgeeft, controleer dan of je server die heeft aangemaakt en of je hetch_-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
returnUrlop 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,
httpsgebruikt 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-idof 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.
Elementfouten
Elk Whop Element accepteert een callbackonError. 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:
- Controleer of het toegangstoken is aangemaakt voor het account dat je verwacht en de scopes bevat die op de referentiepagina van het element staan.
- Geef op je eigen domein altijd een
accessTokendoor. De sessie van de kijker werkt alleen op whop.com. - Controleer of de container bestaat voordat je
mountaanroept. React-componenten mounten zichzelf. - Luister naar
onReadyzodat je weet of het element is geïnitialiseerd. - Als het element in een onherstelbare status terechtkomt, roep dan
destroy()aan en maak een nieuw element aan.
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
SandboxnaarProduction, of verwijder een sandbox-override metbaseUrl/base_url/WithBaseURLuit 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_descriptionof deonError-waarde van het element. - De betrokken Whop-ID’s, zonder geheimen.
- Het event-ID van de webhook of de header
webhook-idbij 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.

