Skip to main content
Lorsque quelque chose ne fonctionne plus, identifiez ce qui échoue, vérifiez que vous ciblez le bon environnement et examinez la réponse d’erreur. La plupart des problèmes se résument à : un mauvais identifiant, une confusion entre sandbox et production, une permission manquante, ou un gestionnaire de webhook qui ne répond pas correctement.

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 :
Certains endpoints OAuth renvoient à la place les champs OAuth standard 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 :
Attendez le délai indiqué dans le message avant de réessayer. Pour les requêtes idempotentes, réessayez avec un backoff exponentiel. Ne réessayez pas les erreurs de validation, d’authentification ou de permission sans modifier la requête.

Authentification API

Utilisez l’identifiant correspondant à l’endroit où le code s’exécute. Si une requête API échoue :
  1. Vérifiez que l’environnement correspond à la clé : l’environnement Production du SDK (par défaut) pour les clés de production et Sandbox pour les clés sandbox, ou https://api.whop.com/api/v1 et https://sandbox-api.whop.com/api/v1 lorsque vous appelez l’API directement.
  2. Vérifiez que les ID utilisent les préfixes Whop comme biz_, user_, mem_, plan_, prod_, app_, pay_ ou ch_, et non des ID numériques internes.
  3. Journalisez le statut HTTP, le corps de la réponse, l’endpoint et l’ID de requête si Whop en renvoie un.
  4. Ne réessayez que lorsque l’erreur est transitoire ou liée à une limite de débit. Ne réessayez pas les erreurs 401, 403 ou de validation sans modifier la requête.
N’exposez jamais de clés API de compte ou de clés API d’app dans du code côté client. Le code navigateur, mobile et d’iframe doit appeler votre serveur, et c’est votre serveur qui doit appeler Whop.

Permissions et scopes

Les erreurs 403 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 contenant error et error_description.
Les URI de redirection doivent correspondre exactement. Si vous avez configuré https://example.com/oauth/callback, https://example.com/oauth/callback/ est une URI différente.

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 un message et un code pour 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 ID ch_.
  • 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 returnUrl sur 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 https et 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 2xx aprè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-id ou 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.
Pour le développement local, redirigez une URL publique vers votre machine avec un tunnel et utilisez cette URL dans les paramètres de webhook du tableau de bord.

Erreurs des éléments

Chaque Whop Element accepte un callback onError. 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 :
Si un élément ne se charge pas :
  1. 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.
  2. Sur votre propre domaine, transmettez toujours un accessToken. La session du visiteur ne fonctionne que sur whop.com.
  3. Vérifiez que le conteneur existe avant d’appeler mount. Les composants React se montent d’eux-mêmes.
  4. Écoutez onReady pour savoir si l’élément s’est initialisé.
  5. Si l’élément entre dans un état irrécupérable, appelez destroy() et créez-en un nouveau.
Le tableau de dépannage des Elements liste les symptômes courants et leurs causes.

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 sandbox baseUrl / base_url / WithBaseURL de 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_description ou la valeur onError de l’élément.
  • Les ID Whop concernés, sans les secrets.
  • L’ID de l’événement webhook ou l’en-tête webhook-id pour 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.