Troubleshooting

When something breaks, figure out what’s failing, check you’re hitting the right environment, and look at the error response. Most issues come down to: wrong credential, sandbox/production mismatch, missing permission, or a webhook handler that isn’t responding correctly.

Quick triage

API request errors

Whop returns standard HTTP status codes. When a request fails, the response body tells you why.

Most errors include a code and a message:

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

Some OAuth endpoints return the OAuth-standard error and error_description fields instead. See OAuth errors for those cases.

Rate limits

For /api/v1 requests, Whop tracks request volume per API operation and API credential. The default limit is 600 requests per minute.

When the limit is exceeded, the API returns 429 with:

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

Wait for the delay in the message before retrying. For idempotent requests, retry with exponential backoff. Do not retry validation, authentication, or permission errors without changing the request.

API authentication

Use the credential that matches where the code runs.

If an API request fails:

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

403 and insufficient_scope errors usually mean the credential is valid but cannot perform that action.

• 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

OAuth errors return a standard payload or redirect query string with error and error_description.

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

Checkout errors

Embedded checkout and iOS checkout can fail for different reasons, but you debug them the same way: check the plan or checkout configuration, inspect the callback, and confirm fulfillment on your server.

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

Handle expected failures separately from unexpected failures:

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

Common webhook issues:

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

For local development, forward a public URL to your machine with a tunnel and use that URL in the dashboard webhook settings.

Embedded element errors

SDK elements such as VerifyElement and ResetAccountElement emit error when initialization or operation fails.

Always attach an error handler while developing:

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

If an element fails to load:

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

Sandbox data and production data are separate.

When switching from sandbox to 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

Include as much of the following as you can:

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