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

빠른 분류

API 요청 오류

Whop은 표준 HTTP 상태 코드를 반환합니다. 요청이 실패하면 응답 본문에 그 이유가 나와 있습니다. 대부분의 오류에는 코드와 메시지가 포함됩니다.
일부 OAuth 엔드포인트는 대신 OAuth 표준 error 및 error_description 필드를 반환합니다. 이러한 경우는 OAuth 오류를 참고하세요.

속도 제한

/api/v1 요청의 경우, Whop은 API 작업 및 API 자격 증명별로 요청량을 추적합니다. 기본 제한은 분당 600회입니다. 제한을 초과하면 API는 다음과 함께 429를 반환합니다.
다시 시도하기 전에 메시지에 나온 시간만큼 기다리세요. 멱등 요청은 지수 백오프를 적용해 다시 시도하세요. 검증, 인증, 권한 오류는 요청을 변경하지 않고 다시 시도하지 마세요.

API 인증

코드가 실행되는 위치에 맞는 자격 증명을 사용하세요. 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 또는 검증 오류는 요청을 변경하지 않고 다시 시도하지 마세요.
계정 API 키나 앱 API 키를 클라이언트 측 코드에 노출하지 마세요. 브라우저, 모바일, iframe 코드는 서버를 호출하고, 서버가 Whop을 호출해야 합니다.

권한 및 스코프

403 및 insufficient_scope 오류는 대개 자격 증명은 유효하지만 해당 작업을 수행할 수 없다는 뜻입니다.
  • Whop 앱의 경우, 앱이 권한에서 필요한 권한을 요청하는지 확인한 다음 앱 설정을 저장하고 필요하면 다시 설치하거나 다시 승인하세요.
  • OAuth의 경우, 기능에 필요한 스코프만 요청하고, 해당 스코프를 추가한 후 사용자가 OAuth 흐름을 완료했는지 확인하세요.
  • 대시보드에서 만든 API 키의 경우, 키가 account_id로 전달하는 ID의 계정에 속하는지 확인하세요.
  • 하위 계정의 경우, 전달할 계정을 선택하기 전에 상위 계정과 하위 계정 중 어느 쪽이 작업을 소유해야 하는지 확인하세요.

OAuth 오류

OAuth 오류는 error와 error_description이 포함된 표준 페이로드 또는 리디렉션 쿼리 문자열을 반환합니다.
리디렉션 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 체크아웃

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

웹훅 전송

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

엘리먼트 오류

모든 Whop Element는 onError 콜백을 받습니다. 엘리먼트가 로드에 실패하거나 충돌할 때 실행되며, 값에는 message, 프로그래밍 방식 처리를 위한 선택적 code, 그리고 호스트 상태 소스가 실패한 경우 sourceKey가 포함됩니다. 개발 중에는 항상 연결하세요.
엘리먼트가 로드에 실패하면:
  1. 액세스 토큰이 예상한 계정에 대해 발급되었고 엘리먼트의 레퍼런스 페이지에 나열된 스코프를 포함하는지 확인하세요.
  2. 자체 도메인에서는 항상 accessToken을 전달하세요. 뷰어의 세션은 whop.com에서만 작동합니다.
  3. mount를 호출하기 전에 컨테이너가 존재하는지 확인하세요. React 컴포넌트는 스스로 마운트됩니다.
  4. onReady를 수신해 엘리먼트가 초기화되었는지 확인하세요.
  5. 엘리먼트가 복구할 수 없는 상태에 들어가면 destroy()를 호출하고 새 엘리먼트를 만드세요.
Elements 문제 해결 표에 흔한 증상과 그 원인이 나와 있습니다.

샌드박스와 프로덕션

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

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

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

OAuth

OAuth 2.1 + PKCE 흐름을 빌드하고 토큰 갱신을 처리하세요.

웹훅

이벤트를 처리하기 전에 서명을 검증하고 재시도를 처리하세요.

권한

앱 권한을 선택하고 크리에이터에게 설명하세요.

샌드박스에서 테스트

프로덕션에 영향을 주지 않고 API 호출과 체크아웃 흐름을 테스트하세요.