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

# Whop 통합 문제 해결

> 실패한 API 요청부터 누락된 웹훅까지, Whop 통합에서 흔히 발생하는 오류를 진단하고 해결하세요.

문제가 발생하면 무엇이 실패하는지 파악하고, 올바른 환경을 호출하고 있는지 확인한 다음 오류 응답을 살펴보세요. 대부분의 문제는 잘못된 자격 증명, 샌드박스/프로덕션 불일치, 누락된 권한, 또는 올바르게 응답하지 않는 웹훅 핸들러로 귀결됩니다.

## 빠른 분류

| 증상 | 먼저 확인할 것 | 자세히 보기 |
| - | - | - |
| API 호출이 `4xx` 또는 `5xx`를 반환함 | 상태 코드, 응답 본문, 엔드포인트, 환경을 확인하세요. | [API 요청 오류](#api-request-errors) |
| API 호출이 `401`을 반환함 | API 키가 서버에 있고 API 기본 URL과 같은 환경에 속하는지 확인하세요. | [API 인증](#api-authentication) |
| API 호출이 `403`을 반환함 | 앱, 사용자 또는 계정에 해당 리소스에 필요한 권한이 있는지 확인하세요. | [권한 및 스코프](#permissions-and-scopes) |
| OAuth가 `error`와 함께 리디렉션됨 | 콜백 URL에서 `error`와 `error_description`을 읽으세요. | [OAuth 오류](#oauth-errors) |
| Checkout 엘리먼트가 로드되지 않거나 결제가 실패함 | `onError`를 연결하고, 전달한 변형 또는 체크아웃 구성을 검사하고, 구매자가 엘리먼트 안에서 다시 시도하게 하세요. | [체크아웃 오류](#checkout-errors) |
| 웹훅이 도착하지 않거나 계속 재시도됨 | 엔드포인트가 공개되어 있고, 오래 걸리는 작업 전에 `2xx`를 빠르게 반환하며, 서명 검증에 원시 요청 본문을 사용하는지 확인하세요. | [웹훅 전송](#webhook-delivery) |
| Whop Element가 `onError`를 보고함 | `message`와 `code`를 기록한 다음 액세스 토큰과 전달한 옵션을 확인하세요. | [엘리먼트 오류](#element-errors) |

## API 요청 오류

Whop은 표준 HTTP 상태 코드를 반환합니다. 요청이 실패하면 응답 본문에 그 이유가 나와 있습니다.

대부분의 오류에는 코드와 메시지가 포함됩니다.

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

일부 OAuth 엔드포인트는 대신 OAuth 표준 `error` 및 `error_description` 필드를 반환합니다. 이러한 경우는 [OAuth 오류](#oauth-errors)를 참고하세요.

| 상태 | 의미 | 해야 할 일 |
| - | - | - |
| `400` | 요청 형식이 잘못되었거나 필수 필드가 없습니다. | 필수 매개변수, enum 값, ID, 중첩 객체 형식을 확인하세요. |
| `401` | 요청에 유효한 인증이 없습니다. | API 키 또는 액세스 토큰이 있고, 유효하며, 서버에서 전송되는지 확인하세요. |
| `403` | 자격 증명은 유효하지만 해당 작업을 수행할 수 없습니다. | 앱 권한, OAuth 스코프, 계정 소유권, 하위 계정 컨텍스트를 확인하세요. |
| `404` | 리소스 또는 엔드포인트를 찾을 수 없습니다. | 라우트, API 버전, `biz_`, `plan_`, `mem_`, `user_` 같은 Whop 태그 ID를 확인하세요. |
| `409` | 요청이 현재 리소스 상태와 충돌합니다. | 최신 리소스 상태를 가져오고, 작업이 여전히 유효한 경우에만 다시 시도하세요. |
| `422` | 요청은 유효한 JSON이지만 검증에 실패했습니다. | 사용자가 입력을 수정할 수 있도록 검증 메시지를 보여 주세요. |
| `429` | 클라이언트가 짧은 시간에 너무 많은 요청을 보냈습니다. | `/api/v1` 요청의 경우, Whop은 인증된 API 호출을 작업 및 API 자격 증명별로 분당 600회로 제한합니다. 오류 메시지에 나온 재시도 대기 시간이 지날 때까지 기다리세요. |
| `5xx` | Whop이 요청을 완료하지 못했습니다. | 멱등 작업은 백오프를 적용해 다시 시도하고, 문제가 지속되면 지원팀에 문의하세요. |

### 속도 제한

`/api/v1` 요청의 경우, Whop은 API 작업 및 API 자격 증명별로 요청량을 추적합니다. 기본 제한은 분당 600회입니다.

제한을 초과하면 API는 다음과 함께 `429`를 반환합니다.

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

다시 시도하기 전에 메시지에 나온 시간만큼 기다리세요. 멱등 요청은 지수 백오프를 적용해 다시 시도하세요. 검증, 인증, 권한 오류는 요청을 변경하지 않고 다시 시도하지 마세요.

## API 인증

코드가 실행되는 위치에 맞는 자격 증명을 사용하세요.

| 자격 증명 | 사용하는 경우 | 흔한 실수 |
| - | - | - |
| 계정 API 키 | 서버가 자신의 계정을 대신해 작동할 때. | 키를 브라우저, 모바일 또는 공개 클라이언트 코드에 넣는 것. |
| 앱 API 키 | 앱 서버가 앱을 설치한 계정을 대신해 작동할 때. | 앱을 설치하거나 승인하지 않은 계정의 엔드포인트를 호출하는 것. |
| 계정 범위 사용자 토큰 | 제품의 자체 사용자가 Whop 로그인 없이 Whop에 접근할 때. | `scoped_actions`를 생략해 토큰이 자신을 발급한 API 키의 모든 권한을 상속하게 되는 것. |
| 계정 액세스 토큰 | 클라이언트가 연결된 사용자 없이 계정에 대한 단기 액세스가 필요할 때. | 사용자로 작동하는 엔드포인트를 호출하는 것. 해당 엔드포인트는 이 토큰을 거부합니다. |
| OAuth 액세스 토큰 | 로그인한 사용자가 앱에 자신의 계정에 대한 액세스를 부여할 때. | 사용자 범위 토큰을 계정 전체 API 키처럼 취급하는 것. |
| iframe 사용자 토큰 | Whop 앱이 iframe 요청 안에서 사용자를 확인할 때. | 서명 검증을 건너뛰거나 토큰을 관련 없는 클라이언트에 전달하는 것. |

API 요청이 실패하면:

1. 환경이 키와 일치하는지 확인하세요. 프로덕션 키에는 SDK의 `Production` 환경(기본값)을, 샌드박스 키에는 `Sandbox`를 사용하고, API를 직접 호출할 때는 `https://api.whop.com/api/v1`과 `https://sandbox-api.whop.com/api/v1`을 사용하세요.
2. ID가 내부 숫자 ID가 아니라 `biz_`, `user_`, `mem_`, `plan_`, `prod_`, `app_`, `pay_`, `ch_` 같은 Whop 태그 접두사를 사용하는지 확인하세요.
3. HTTP 상태, 응답 본문, 엔드포인트, 그리고 Whop이 반환한 경우 요청 ID를 기록하세요.
4. 오류가 일시적이거나 속도 제한에 걸린 경우에만 다시 시도하세요. `401`, `403` 또는 검증 오류는 요청을 변경하지 않고 다시 시도하지 마세요.

> [!WARNING]
>
> 계정 API 키나 앱 API 키를 클라이언트 측 코드에 노출하지 마세요. 브라우저, 모바일, iframe 코드는 서버를 호출하고, 서버가 Whop을 호출해야 합니다.

## 권한 및 스코프

`403` 및 `insufficient_scope` 오류는 대개 자격 증명은 유효하지만 해당 작업을 수행할 수 없다는 뜻입니다.

* Whop 앱의 경우, 앱이 [권한](https://docs.whop.com/ko/developer/guides/permissions.md)에서 필요한 권한을 요청하는지 확인한 다음 앱 설정을 저장하고 필요하면 다시 설치하거나 다시 승인하세요.
* OAuth의 경우, 기능에 필요한 스코프만 요청하고, 해당 스코프를 추가한 후 사용자가 OAuth 흐름을 완료했는지 확인하세요.
* 대시보드에서 만든 API 키의 경우, 키가 `account_id`로 전달하는 ID의 계정에 속하는지 확인하세요.
* 하위 계정의 경우, 전달할 계정을 선택하기 전에 상위 계정과 하위 계정 중 어느 쪽이 작업을 소유해야 하는지 확인하세요.

## OAuth 오류

OAuth 오류는 `error`와 `error_description`이 포함된 표준 페이로드 또는 리디렉션 쿼리 문자열을 반환합니다.

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

| 오류 | 의미 | 해결 방법 |
| - | - | - |
| `invalid_request` | 필수 매개변수가 없거나 형식이 잘못되었습니다. | `client_id`, `redirect_uri`, `response_type`, `code_challenge`, `code_challenge_method`를 확인하세요. |
| `invalid_grant` | 인증 코드, 리프레시 토큰 또는 액세스 토큰이 만료되었거나, 이미 사용되었거나, Whop이 취소했습니다. | OAuth 흐름을 다시 시작하거나 사용자에게 다시 로그인하도록 요청하세요. 인증 코드는 한 번만 사용할 수 있습니다. |
| `invalid_client` | Whop이 앱 클라이언트를 인식하지 못합니다. | 올바른 앱과 환경을 사용하고 있는지 확인하세요. |
| `invalid_scope` | 요청한 스코프가 유효하지 않거나 인식되지 않습니다. | 앱 설정에서 사용 가능한 스코프를 확인하고 오타를 제거하세요. |
| `insufficient_scope` | 토큰에 엔드포인트에 필요한 스코프가 포함되어 있지 않습니다. | 앱 설정에 스코프를 추가하고 OAuth 동의를 다시 실행하세요. |
| `access_denied` | 사용자 또는 계정이 승인 요청을 거부했습니다. | 사용자가 액세스 부여를 선택하지 않았거나, 계정이 이 앱을 제한합니다. |
| `unsupported_response_type` | `response_type` 매개변수가 지원되지 않습니다. | 인증 코드 흐름에는 `response_type=code`를 사용하세요. |
| `unsupported_grant_type` | `grant_type` 매개변수가 지원되지 않습니다. | `authorization_code` 또는 `refresh_token`을 사용하세요. |
| `rate_limit_exceeded` | OAuth 승인, 토큰 또는 인트로스펙션 요청이 단기 제한에 걸렸습니다. | 백오프하고, `Retry-After` 헤더가 있으면 이를 따르세요. |

> [!TIP]
>
> 리디렉션 URI는 정확히 일치해야 합니다. `https://example.com/oauth/callback`을 구성했다면 `https://example.com/oauth/callback/`은 다른 URI입니다.

## 체크아웃 오류

Checkout 엘리먼트와 iOS 체크아웃은 서로 다른 이유로 실패할 수 있습니다. 디버깅 방법은 같습니다. 변형 또는 체크아웃 구성을 확인하고, 오류 콜백을 검사하고, 서버에서 이행을 확인하세요.

### Checkout 엘리먼트

* `onError`를 연결하세요. 엘리먼트가 로드에 실패하거나 충돌할 때 실행되며, 프로그래밍 방식 처리를 위한 `message`와 `code`를 제공합니다.
* 호환성 속성 `plan`을 전달하는 경우, 변형이 존재하고 활성 상태이며 예상한 계정에 속하는지 확인하세요.
* `checkoutConfiguration`을 전달하는 경우, 서버가 이를 생성했고 해당 `ch_` ID를 전달했는지 확인하세요.
* 모든 옵션은 생성 시 설정됩니다. 주문을 변경하려면 `update()`를 호출하는 대신 새 체크아웃을 마운트하세요.
* 결제가 실패하면 같은 체크아웃이 실패 사유와 함께 다시 열리므로, 구매자는 다시 마운트하지 않고도 다시 결제할 수 있습니다.
* 성공 및 재시도 상태를 렌더링할 수 있는 라우트에 `returnUrl`을 제공하세요. 3DS나 은행 페이지 같은 외부 단계가 끝나면 구매자가 그곳으로 돌아옵니다.
* 이행에는 웹훅을 사용하세요. 리디렉션은 UI에 유용하지만, 서버는 `payment.succeeded`에 의존해야 합니다.

### `iOS` 체크아웃

예상된 실패와 예상치 못한 실패를 서로 다른 경로로 처리하세요.

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

## 웹훅 전송

흔한 웹훅 문제:

* **이벤트를 받지 못함**: 웹훅 URL이 공개적으로 접근 가능하고, `https`를 사용하며, 올바른 계정과 환경에 속하는지 확인하세요.
* **서명 검증 실패**: 원시 요청 본문을 `unwrapWebhook`에 전달하세요. 검증 전에 JSON을 파싱하지 마세요.
* **재시도가 계속 발생함**: 백그라운드 작업에서 오래 걸리는 작업을 시작하기 전에, 검증 후 빠르게 `2xx` 응답을 반환하세요.
* **중복 이행**: Whop은 웹훅을 최소 한 번 전송합니다. `webhook-id` 또는 다른 이벤트 식별자를 저장하고 핸들러를 멱등하게 만드세요.
* **예상치 못한 순서**: 이벤트가 시간순으로 도착한다고 가정하지 마세요. 순서가 중요할 때는 현재 리소스 상태를 가져오세요.

로컬 개발의 경우, 터널로 공개 URL을 로컬 머신에 전달하고 대시보드 웹훅 설정에서 해당 URL을 사용하세요.

## 엘리먼트 오류

모든 [Whop Element](https://docs.whop.com/ko/elements/latest/getting-started.md)는 `onError` 콜백을 받습니다. 엘리먼트가 로드에 실패하거나 충돌할 때 실행되며, 값에는 `message`, 프로그래밍 방식 처리를 위한 선택적 `code`, 그리고 호스트 상태 소스가 실패한 경우 `sourceKey`가 포함됩니다.

개발 중에는 항상 연결하세요.

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

엘리먼트가 로드에 실패하면:

1. 액세스 토큰이 예상한 계정에 대해 발급되었고 엘리먼트의 레퍼런스 페이지에 나열된 스코프를 포함하는지 확인하세요.
2. 자체 도메인에서는 항상 `accessToken`을 전달하세요. 뷰어의 세션은 whop.com에서만 작동합니다.
3. `mount`를 호출하기 전에 컨테이너가 존재하는지 확인하세요. React 컴포넌트는 스스로 마운트됩니다.
4. `onReady`를 수신해 엘리먼트가 초기화되었는지 확인하세요.
5. 엘리먼트가 복구할 수 없는 상태에 들어가면 `destroy()`를 호출하고 새 엘리먼트를 만드세요.

[Elements 문제 해결 표](https://docs.whop.com/ko/elements/latest/getting-started.md#troubleshooting)에 흔한 증상과 그 원인이 나와 있습니다.

## 샌드박스와 프로덕션

샌드박스 데이터와 프로덕션 데이터는 분리되어 있습니다.

| 환경 | 대시보드 | API |
| - | - | - |
| 샌드박스 | `https://sandbox.whop.com` | `https://sandbox-api.whop.com/api/v1` |
| 프로덕션 | `https://whop.com` | `https://api.whop.com/api/v1` |

샌드박스에서 프로덕션으로 전환할 때:

* 새 프로덕션 API 키를 만드세요.
* SDK 환경을 `Sandbox`에서 `Production`으로 바꾸거나, 1.x의 `baseUrl` / `base_url` / `WithBaseURL` 샌드박스 재정의를 제거하세요.
* 샌드박스 전용 상품, 체크아웃 링크, 웹훅, 하위 계정 레코드를 프로덕션에서 다시 만드세요.
* 웹훅 URL이 로컬 터널이 아니라 프로덕션 인프라를 가리키는지 확인하세요.

## 도움을 요청할 때 포함할 내용

다음 내용을 가능한 한 많이 포함하세요.

* 실패한 엔드포인트, SDK 메서드 또는 엘리먼트 이름.
* 환경: 샌드박스 또는 프로덕션.
* 상태 코드, 오류 본문, OAuth `error_description` 또는 엘리먼트 `onError` 값.
* 관련된 Whop ID(시크릿은 제거).
* 웹훅 문제의 경우 웹훅 이벤트 ID 또는 `webhook-id` 헤더.
* 클라이언트, 체크아웃, OAuth URL, 웹훅 핸들러 또는 엘리먼트를 만드는 방법을 보여 주는 짧은 코드 스니펫.

> [card] [OAuth](https://docs.whop.com/ko/developer/guides/oauth.md)
>
> OAuth 2.1 + PKCE 흐름을 빌드하고 토큰 갱신을 처리하세요.

> [card] [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 이벤트를 처리하기 전에 서명을 검증하고 재시도를 처리하세요.

> [card] [권한](https://docs.whop.com/ko/developer/guides/permissions.md)
>
> 앱 권한을 선택하고 크리에이터에게 설명하세요.

> [card] [샌드박스에서 테스트](https://docs.whop.com/ko/developer/guides/sandbox.md)
>
> 프로덕션에 영향을 주지 않고 API 호출과 체크아웃 흐름을 테스트하세요.


## Related topics

- [GoHighLevel](https://docs.whop.com/ko/third-party-integrations/gohighlevel.md)
- [Whop API 개요](https://docs.whop.com/ko/api-reference/overview.md)
- [React Native로 Whop 앱 구축하기](https://docs.whop.com/ko/developer/guides/react-native.md)
