Tri rapide
Erreurs de requête API
Whop renvoie des codes de statut HTTP standard. Lorsqu’une requête échoue, le corps de la réponse en indique la raison. La plupart des erreurs incluent un code et un message :error et error_description. Consultez Erreurs OAuth pour ces cas.
Limites de débit
Pour les requêtes/api/v1, Whop suit le volume de requêtes par opération d’API et par identifiant API. La limite par défaut est de 600 requêtes par minute.
Lorsque vous dépassez la limite, l’API renvoie 429 avec :
Authentification API
Utilisez l’identifiant correspondant à l’endroit où le code s’exécute.
Si une requête API échoue :
- Vérifiez que l’environnement correspond à la clé : l’environnement
Productiondu SDK (par défaut) pour les clés de production etSandboxpour les clés sandbox, ouhttps://api.whop.com/api/v1ethttps://sandbox-api.whop.com/api/v1lorsque vous appelez l’API directement. - Vérifiez que les ID utilisent les préfixes Whop comme
biz_,user_,mem_,plan_,prod_,app_,pay_ouch_, et non des ID numériques internes. - Journalisez le statut HTTP, le corps de la réponse, l’endpoint et l’ID de requête si Whop en renvoie un.
- Ne réessayez que lorsque l’erreur est transitoire ou liée à une limite de débit. Ne réessayez pas les erreurs
401,403ou de validation sans modifier la requête.
Permissions et scopes
Les erreurs403 et insufficient_scope signifient généralement que l’identifiant est valide mais ne peut pas effectuer cette action.
- Pour les apps Whop, vérifiez que l’app demande les permissions requises dans Permissions, puis enregistrez les paramètres de l’app et réinstallez-la ou réautorisez-la si nécessaire.
- Pour OAuth, demandez uniquement les scopes dont votre fonctionnalité a besoin, puis assurez-vous que l’utilisateur a terminé le flux OAuth après l’ajout de ces scopes.
- Pour les clés API créées depuis le tableau de bord, vérifiez que la clé appartient au compte dont vous transmettez l’ID dans
account_id. - Pour les sous-comptes, déterminez si l’action doit appartenir au compte parent ou au compte enfant avant de choisir le compte à transmettre.
Erreurs OAuth
Les erreurs OAuth renvoient un payload standard ou une query string de redirection contenanterror et error_description.
Erreurs de checkout
L’élément Checkout et le checkout iOS peuvent échouer pour des raisons différentes. Déboguez-les de la même façon : vérifiez la variante ou la configuration de checkout, inspectez le callback d’erreur et confirmez le traitement de la commande sur votre serveur.Élément Checkout
- Attachez
onError. Il s’exécute lorsque l’élément ne se charge pas ou plante, avec unmessageet uncodepour un traitement programmatique. - Si vous transmettez la propriété de compatibilité
plan, vérifiez que la variante existe, est active et appartient au compte attendu. - Si vous transmettez
checkoutConfiguration, vérifiez que votre serveur l’a créée et que vous avez transmis son IDch_. - Toutes les options sont définies à la création. Pour modifier la commande, montez un nouveau checkout au lieu d’appeler
update(). - Un paiement échoué rouvre le même checkout en affichant la raison, afin que l’acheteur puisse payer à nouveau sans remontage.
- Fournissez une
returnUrlsur une route capable d’afficher les états de réussite et de nouvelle tentative. Une étape externe comme 3DS ou une page bancaire y renvoie l’acheteur. - Utilisez les webhooks pour le traitement des commandes. La redirection est utile pour l’interface, mais votre serveur doit s’appuyer sur
payment.succeeded.
Checkout iOS
Traitez les échecs attendus et inattendus par des chemins différents :
Livraison des webhooks
Problèmes de webhook courants :- Aucun événement reçu : vérifiez que l’URL du webhook est accessible publiquement, utilise
httpset appartient au bon compte et au bon environnement. - La vérification de signature échoue : transmettez le corps brut de la requête à
unwrapWebhook. Ne parsez pas le JSON avant la vérification. - Les nouvelles tentatives se répètent : renvoyez rapidement une réponse
2xxaprès la vérification, avant de lancer un traitement long dans une tâche en arrière-plan. - Traitement en double : Whop livre les webhooks au moins une fois. Stockez
webhook-idou un autre identifiant d’événement et rendez le gestionnaire idempotent. - Ordre inattendu : ne supposez pas que les événements arrivent dans l’ordre chronologique. Récupérez l’état actuel de la ressource lorsque l’ordre compte.
Erreurs des éléments
Chaque Whop Element accepte un callbackonError. Il s’exécute lorsque l’élément ne se charge pas ou plante, et la valeur contient un message, un code facultatif pour un traitement programmatique, ainsi qu’un sourceKey lorsqu’une source d’état hôte a échoué.
Attachez-le toujours pendant le développement :
- Vérifiez que le jeton d’accès a été émis pour le compte attendu et qu’il contient les scopes listés sur la page de référence de l’élément.
- Sur votre propre domaine, transmettez toujours un
accessToken. La session du visiteur ne fonctionne que sur whop.com. - Vérifiez que le conteneur existe avant d’appeler
mount. Les composants React se montent d’eux-mêmes. - Écoutez
onReadypour savoir si l’élément s’est initialisé. - Si l’élément entre dans un état irrécupérable, appelez
destroy()et créez-en un nouveau.
Sandbox et production
Les données sandbox et les données de production sont séparées.
Lors du passage du sandbox à la production :
- Créez de nouvelles clés API de production.
- Passez l’environnement du SDK de
SandboxàProduction, ou supprimez une surcharge sandboxbaseUrl/base_url/WithBaseURLde la version 1.x. - Recréez en production les produits, liens de checkout, webhooks et enregistrements de sous-comptes propres au sandbox.
- Vérifiez que les URL de webhook pointent vers l’infrastructure de production, et non vers un tunnel local.
Que fournir lorsque vous demandez de l’aide
Incluez autant d’éléments suivants que possible :- L’endpoint, la méthode du SDK ou le nom de l’élément qui a échoué.
- L’environnement : sandbox ou production.
- Le code de statut, le corps de l’erreur, la valeur OAuth
error_descriptionou la valeuronErrorde l’élément. - Les ID Whop concernés, sans les secrets.
- L’ID de l’événement webhook ou l’en-tête
webhook-idpour les problèmes de webhook. - Un court extrait de code montrant comment vous créez le client, le checkout, l’URL OAuth, le gestionnaire de webhook ou l’élément.
OAuth
Mettez en place le flux OAuth 2.1 + PKCE et gérez l’actualisation des jetons.
Webhooks
Vérifiez les signatures avant de traiter les événements, et gérez les nouvelles tentatives.
Permissions
Choisissez les permissions de l’app et expliquez-les aux créateurs.
Tester dans le sandbox
Testez les appels API et les flux de checkout sans toucher à la production.

