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

# Dépanner les intégrations Whop

> Diagnostiquez et corrigez les erreurs courantes d'une intégration Whop, des requêtes API qui échouent aux webhooks manquants.

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

| Symptôme | Première vérification | Aller plus loin |
| - | - | - |
| Les appels API renvoient `4xx` ou `5xx` | Vérifiez le code de statut, le corps de la réponse, l'endpoint et l'environnement. | [Erreurs de requête API](#api-request-errors) |
| Les appels API renvoient `401` | Vérifiez que la clé API est présente sur le serveur et appartient au même environnement que l'URL de base de l'API. | [Authentification API](#api-authentication) |
| Les appels API renvoient `403` | Vérifiez que l'app, l'utilisateur ou le compte dispose de la permission requise pour la ressource. | [Permissions et scopes](#permissions-and-scopes) |
| OAuth redirige avec `error` | Lisez `error` et `error_description` dans l'URL de callback. | [Erreurs OAuth](#oauth-errors) |
| L'élément Checkout ne se charge pas ou le paiement échoue | Attachez `onError`, inspectez la variante ou la configuration de checkout transmise, et laissez l'acheteur réessayer dans l'élément. | [Erreurs de checkout](#checkout-errors) |
| Les webhooks n'arrivent pas ou sont sans cesse renvoyés | Vérifiez que l'endpoint est public, renvoie rapidement un `2xx` avant tout traitement long, et utilise le corps brut de la requête pour vérifier la signature. | [Livraison des webhooks](#webhook-delivery) |
| Un Whop Element signale `onError` | Journalisez `message` et `code`, puis vérifiez le jeton d'accès et les options transmises. | [Erreurs des éléments](#element-errors) |

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

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

Certains endpoints OAuth renvoient à la place les champs OAuth standard `error` et `error_description`. Consultez [Erreurs OAuth](#oauth-errors) pour ces cas.

| Statut | Signification | Que faire |
| - | - | - |
| `400` | La requête a une forme invalide ou il manque un champ obligatoire. | Vérifiez les paramètres obligatoires, les valeurs d'enum, les ID et la forme des objets imbriqués. |
| `401` | La requête ne comporte pas d'authentification valide. | Vérifiez que la clé API ou le jeton d'accès est présent, valide et envoyé depuis votre serveur. |
| `403` | L'identifiant est valide mais ne peut pas effectuer l'action. | Vérifiez les permissions de l'app, les scopes OAuth, la propriété du compte et le contexte du sous-compte. |
| `404` | La ressource ou l'endpoint est introuvable. | Vérifiez la route, la version d'API et l'ID Whop tel que `biz_`, `plan_`, `mem_` ou `user_`. |
| `409` | La requête entre en conflit avec l'état actuel de la ressource. | Récupérez l'état le plus récent de la ressource et ne réessayez que si l'action s'applique toujours. |
| `422` | La requête est un JSON valide mais échoue à la validation. | Affichez le message de validation à l'utilisateur pour qu'il puisse corriger sa saisie. |
| `429` | Le client a envoyé trop de requêtes en peu de temps. | Pour les requêtes `/api/v1`, Whop limite les appels API authentifiés à 600 requêtes par minute par opération et par identifiant API. Patientez jusqu'à la fin du délai indiqué dans le message d'erreur. |
| `5xx` | Whop n'a pas pu traiter la requête. | Réessayez avec un backoff pour les opérations idempotentes, puis contactez le support si le problème persiste. |

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

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

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.

| Identifiant | À utiliser lorsque | Erreur courante |
| - | - | - |
| Clé API de compte | Votre serveur agit pour votre propre compte. | Placer la clé dans du code client navigateur, mobile ou public. |
| Clé API d'app | Le serveur de votre app agit pour les comptes qui ont installé votre app. | Appeler des endpoints pour un compte qui n'a pas installé ou autorisé l'app. |
| Jeton utilisateur limité à un compte | Les utilisateurs de votre propre produit accèdent à Whop sans connexion Whop. | Omettre `scoped_actions`, si bien que le jeton hérite de toutes les permissions de la clé API qui l'a émis. |
| Jeton d'accès de compte | Un client a besoin d'un accès de courte durée à votre compte sans utilisateur associé. | Appeler des endpoints qui agissent en tant qu'utilisateur, et qui le rejettent. |
| Jeton d'accès OAuth | Un utilisateur connecté accorde à votre app l'accès à son compte. | Traiter un jeton limité à l'utilisateur comme une clé API valable pour tout le compte. |
| Jeton utilisateur d'iframe | Une app Whop vérifie l'utilisateur dans une requête d'iframe. | Ignorer la vérification de signature ou transmettre le jeton à des clients sans rapport. |

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.

> [!WARNING]
>
> 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](https://docs.whop.com/fr/developer/guides/permissions.md), 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`.

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

| Erreur | Signification | Correction |
| - | - | - |
| `invalid_request` | Un paramètre obligatoire est manquant ou mal formé. | Vérifiez `client_id`, `redirect_uri`, `response_type`, `code_challenge` et `code_challenge_method`. |
| `invalid_grant` | Le code d'autorisation, le jeton d'actualisation ou le jeton d'accès a expiré, a déjà été utilisé ou a été révoqué par Whop. | Relancez le flux OAuth ou demandez à l'utilisateur de se reconnecter. Les codes d'autorisation sont à usage unique. |
| `invalid_client` | Whop ne reconnaît pas le client de l'app. | Vérifiez que vous utilisez la bonne app et le bon environnement. |
| `invalid_scope` | Le scope demandé n'est pas valide ou n'est pas reconnu. | Vérifiez les scopes disponibles dans les paramètres de votre app et corrigez les éventuelles fautes de frappe. |
| `insufficient_scope` | Le jeton n'inclut pas le scope requis par l'endpoint. | Ajoutez le scope dans les paramètres de votre app et relancez le consentement OAuth. |
| `access_denied` | L'utilisateur ou le compte a refusé la demande d'autorisation. | L'utilisateur a choisi de ne pas accorder l'accès, ou le compte restreint cette app. |
| `unsupported_response_type` | Le paramètre `response_type` n'est pas pris en charge. | Utilisez `response_type=code` pour le flux du code d'autorisation. |
| `unsupported_grant_type` | Le paramètre `grant_type` n'est pas pris en charge. | Utilisez `authorization_code` ou `refresh_token`. |
| `rate_limit_exceeded` | Les requêtes OAuth d'autorisation, de jeton ou d'introspection ont atteint une limite sur une courte période. | Patientez et respectez l'en-tête `Retry-After` s'il est présent. |

> [!TIP]
>
> 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 :

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

## 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](https://docs.whop.com/fr/elements/latest/getting-started.md) 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 :

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

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](https://docs.whop.com/fr/elements/latest/getting-started.md#troubleshooting) 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.

| Environnement | Tableau de bord | API |
| - | - | - |
| Sandbox | `https://sandbox.whop.com` | `https://sandbox-api.whop.com/api/v1` |
| Production | `https://whop.com` | `https://api.whop.com/api/v1` |

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.

> [card] [OAuth](https://docs.whop.com/fr/developer/guides/oauth.md)
>
> Mettez en place le flux OAuth 2.1 + PKCE et gérez l'actualisation des jetons.

> [card] [Webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md)
>
> Vérifiez les signatures avant de traiter les événements, et gérez les nouvelles tentatives.

> [card] [Permissions](https://docs.whop.com/fr/developer/guides/permissions.md)
>
> Choisissez les permissions de l'app et expliquez-les aux créateurs.

> [card] [Tester dans le sandbox](https://docs.whop.com/fr/developer/guides/sandbox.md)
>
> Testez les appels API et les flux de checkout sans toucher à la production.


## Related topics

- [Exemple d'intégration](https://docs.whop.com/fr/developer/guides/example-integration.md)
- [Installer les SDK iOS de Whop](https://docs.whop.com/fr/developer/guides/ios/installation.md)
- [Installer le pixel Whop avec Calendly](https://docs.whop.com/fr/developer/ads/platforms/calendly.md)
