빠른 분류
API 요청 오류
Whop은 표준 HTTP 상태 코드를 반환합니다. 요청이 실패하면 응답 본문에 그 이유가 나와 있습니다. 대부분의 오류에는 코드와 메시지가 포함됩니다.error 및 error_description 필드를 반환합니다. 이러한 경우는 OAuth 오류를 참고하세요.
속도 제한
/api/v1 요청의 경우, Whop은 API 작업 및 API 자격 증명별로 요청량을 추적합니다. 기본 제한은 분당 600회입니다.
제한을 초과하면 API는 다음과 함께 429를 반환합니다.
API 인증
코드가 실행되는 위치에 맞는 자격 증명을 사용하세요.
API 요청이 실패하면:
- 환경이 키와 일치하는지 확인하세요. 프로덕션 키에는 SDK의
Production환경(기본값)을, 샌드박스 키에는Sandbox를 사용하고, API를 직접 호출할 때는https://api.whop.com/api/v1과https://sandbox-api.whop.com/api/v1을 사용하세요. - ID가 내부 숫자 ID가 아니라
biz_,user_,mem_,plan_,prod_,app_,pay_,ch_같은 Whop 태그 접두사를 사용하는지 확인하세요. - HTTP 상태, 응답 본문, 엔드포인트, 그리고 Whop이 반환한 경우 요청 ID를 기록하세요.
- 오류가 일시적이거나 속도 제한에 걸린 경우에만 다시 시도하세요.
401,403또는 검증 오류는 요청을 변경하지 않고 다시 시도하지 마세요.
권한 및 스코프
403 및 insufficient_scope 오류는 대개 자격 증명은 유효하지만 해당 작업을 수행할 수 없다는 뜻입니다.
- Whop 앱의 경우, 앱이 권한에서 필요한 권한을 요청하는지 확인한 다음 앱 설정을 저장하고 필요하면 다시 설치하거나 다시 승인하세요.
- OAuth의 경우, 기능에 필요한 스코프만 요청하고, 해당 스코프를 추가한 후 사용자가 OAuth 흐름을 완료했는지 확인하세요.
- 대시보드에서 만든 API 키의 경우, 키가
account_id로 전달하는 ID의 계정에 속하는지 확인하세요. - 하위 계정의 경우, 전달할 계정을 선택하기 전에 상위 계정과 하위 계정 중 어느 쪽이 작업을 소유해야 하는지 확인하세요.
OAuth 오류
OAuth 오류는error와 error_description이 포함된 표준 페이로드 또는 리디렉션 쿼리 문자열을 반환합니다.
체크아웃 오류
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또는 다른 이벤트 식별자를 저장하고 핸들러를 멱등하게 만드세요. - 예상치 못한 순서: 이벤트가 시간순으로 도착한다고 가정하지 마세요. 순서가 중요할 때는 현재 리소스 상태를 가져오세요.
엘리먼트 오류
모든 Whop Element는onError 콜백을 받습니다. 엘리먼트가 로드에 실패하거나 충돌할 때 실행되며, 값에는 message, 프로그래밍 방식 처리를 위한 선택적 code, 그리고 호스트 상태 소스가 실패한 경우 sourceKey가 포함됩니다.
개발 중에는 항상 연결하세요.
- 액세스 토큰이 예상한 계정에 대해 발급되었고 엘리먼트의 레퍼런스 페이지에 나열된 스코프를 포함하는지 확인하세요.
- 자체 도메인에서는 항상
accessToken을 전달하세요. 뷰어의 세션은 whop.com에서만 작동합니다. mount를 호출하기 전에 컨테이너가 존재하는지 확인하세요. React 컴포넌트는 스스로 마운트됩니다.onReady를 수신해 엘리먼트가 초기화되었는지 확인하세요.- 엘리먼트가 복구할 수 없는 상태에 들어가면
destroy()를 호출하고 새 엘리먼트를 만드세요.
샌드박스와 프로덕션
샌드박스 데이터와 프로덕션 데이터는 분리되어 있습니다.
샌드박스에서 프로덕션으로 전환할 때:
- 새 프로덕션 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 호출과 체크아웃 흐름을 테스트하세요.

