Troubleshooting

​

Quick triage

​

API request errors

{
	"error": {
		"code": "invalid_request",
		"message": "Missing required parameter: company_id"
	}
}

​

Rate limits

{
	"error": {
		"type": "rate_limit_exceeded",
		"message": "Try again in 12 seconds."
	}
}

​

API authentication

1. Confirm the environment matches the key: the SDK’s Production environment (the default) for production keys and Sandbox for sandbox keys, or https://api.whop.com/api/v1 and https://sandbox-api.whop.com/api/v1 when you call the API directly.
2. Confirm IDs use Whop tag prefixes like biz_, user_, mem_, plan_, prod_, app_, pay_, or ch_, not internal numeric IDs.
3. Log the HTTP status, response body, endpoint, and request ID if Whop returns one.
4. Retry only when the error is transient or rate-limited. Don’t retry 401, 403, or validation errors without changing the request.

​

Permissions and scopes

• For Whop apps, confirm the app requests the required permissions in Permissions, then save the app settings and reinstall or reauthorize when needed.
• For OAuth, request only the scopes your feature needs, then make sure the user completed the OAuth flow after you added those scopes.
• For dashboard-created API keys, confirm the key belongs to the account whose ID you pass (company_id or account_id, depending on the endpoint).
• For connected accounts, confirm whether the parent or child account should own the action before choosing the account you pass.

​

OAuth errors

{
	"error": "invalid_grant",
	"error_description": "Authorization code has expired"
}

​

Checkout errors

​

Checkout element

• Attach onError. It runs when the element fails to load or crashes, with a message and a code for programmatic handling.
• If you pass the compatibility property plan, confirm the variant exists, is active, and belongs to the account you expect.
• If you pass checkoutConfiguration, confirm your server created it and that you passed its ch_ ID.
• Every option is set at creation. To change the order, mount a new checkout instead of calling update().
• A failed payment reopens the same checkout with the reason shown, so the buyer can pay again without a remount.
• Provide a returnUrl on a route that can render success and retry states. An off-site step such as 3DS or a bank page returns the buyer there.
• Use webhooks for fulfillment. The redirect is useful for UI, but your server should rely on payment.succeeded.

​

iOS checkout

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

​

Webhook delivery

• No event received: confirm the webhook URL is publicly reachable, uses https, and belongs to the right account and environment.
• Signature verification fails: pass the raw request body to unwrapWebhook. Don’t parse JSON before verification.
• Retries keep happening: return a 2xx response quickly after verification, before starting long-running work in a background job.
• Duplicate fulfillment: Whop delivers webhooks at least once. Store webhook-id or another event identifier and make the handler idempotent.
• Unexpected order: don’t assume events arrive in chronological order. Fetch the current resource state when ordering matters.

​

Element errors

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

1. Confirm the access token was minted for the account you expect and carries the scopes the element’s reference page lists.
2. On your own domain, always pass an accessToken. The viewer’s session only works on whop.com.
3. Confirm the container exists before calling mount. React components mount themselves.
4. Listen for onReady so you know whether the element initialized.
5. If the element enters an unrecoverable state, call destroy() and create a new one.

​

Sandbox and production

• Create new production API keys.
• Switch the SDK environment from Sandbox to Production, or remove a 1.x baseUrl / base_url / WithBaseURL sandbox override.
• Recreate sandbox-only products, checkout links, webhooks, and connected-account records in production.
• Confirm webhook URLs point to production infrastructure, not a local tunnel.

​

What to include when asking for help

• The endpoint, SDK method, or element name that failed.
• The environment: sandbox or production.
• The status code, error body, OAuth error_description, or element onError value.
• The Whop IDs involved, with secrets removed.
• The webhook event ID or webhook-id header for webhook issues.
• A short code snippet showing how you create the client, checkout, OAuth URL, webhook handler, or element.