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 base URL matches the key: use https://api.whop.com/api/v1 for production keys and https://sandbox-api.whop.com/api/v1 for sandbox keys.
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 one is returned.
4. Retry only when the error is transient or rate-limited. Do not 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 those scopes were added.
• For dashboard-created API keys, confirm the key belongs to the company you are passing as company_id.
• For connected accounts, confirm whether the parent company or child company should own the action before choosing the company_id.

​

OAuth errors

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

​

Checkout errors

​

Embedded checkout

• If checkout redirects to returnUrl with status=error, show a retry state and remount checkout.
• If you pass planId, confirm the plan exists, is active, and belongs to the company you expect.
• If you pass sessionId, confirm the checkout configuration was created server-side and the session has not expired.
• If external payment methods redirect away from your page, make sure returnUrl is set and points to a route that can render success and retry states.
• Use webhooks for fulfillment. Client-side onComplete or redirect status 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 is saved on the right company and environment.
• Signature verification fails: pass the raw request body to whopsdk.webhooks.unwrap. Do not parse JSON before verification.
• Retries keep happening: return a 2xx response quickly after verification, then do long-running work in a background job.
• Duplicate fulfillment: webhooks are delivered at least once. Store webhook-id or another event identifier and make the handler idempotent.
• Unexpected order: do not assume events arrive in chronological order. Fetch the current resource state when ordering matters.

​

Embedded element errors

const element = session.createElement("verify-element", {
	onError: (error) => {
		console.error("VerifyElement failed", error);
	},
});

element.mount("#verify-container");

1. Confirm the session token was created for the company and user you expect.
2. Confirm the container exists and is empty before calling mount.
3. Listen for ready so you know whether the element initialized.
4. If the element enters an unrecoverable state, call unmount() and create a new element instance.
5. For payout and verification elements, confirm the user is eligible for that flow in the current environment.

​

Sandbox and production

• Create new production API keys.
• Remove the SDK baseURL / base_url 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.