오류 코드: CheckoutOS 문서

이 참조 문서는 CheckoutOS 사용 중 발생할 수 있는 오류 코드를 다뤄요. 각 오류의 의미와 권장 해결 단계를 안내해요.

오류 코드 찾기

오류 코드는 CheckoutOS 대시보드 알림, 브라우저 콘솔, 웹훅 응답에 표시돼요. COS-XXXX 형식의 코드를 찾으세요.

설치 오류(COS-1XXX)

COS-1001: Shopify 연결 실패

원인: Shopify 스토어에 연결할 수 없어요.

해결 방법:

Shopify 스토어 URL이 올바른지 확인하세요
스토어가 일시 중지 또는 보류 상태가 아닌 활성 상태인지 확인하세요
Shopify App Store에서 CheckoutOS 앱을 다시 설치하세요
스토어 관리자 또는 소유자 권한이 있는지 확인하세요

COS-1002: 권한 거부

원인: CheckoutOS에 필요한 권한이 없어요.

해결 방법:

앱을 다시 설치해 권한을 다시 승인하세요
스토어 소유자나 관리자로 로그인했는지 확인하세요
Shopify Admin → Apps → CheckoutOS에서 권한 상태를 확인하세요

COS-1003: Checkout Extensibility 사용 불가

원인: Shopify 요금제가 결제 확장 기능을 지원하지 않아요.

해결 방법:

전체 결제 확장 기능을 사용하려면 Shopify Plus로 업그레이드하세요
Plus가 아닌 스토어는 Checkout Extensibility 베타 접근 권한을 신청하세요
모든 요금제에서 사용할 수 있는 구매 후 기능만 사용하세요

캠페인 오류(COS-2XXX)

COS-2001: 잘못된 캠페인 설정

원인: 캠페인 설정이 누락되었거나 유효하지 않아요.

해결 방법:

캠페인의 모든 필수 필드를 검토하세요
추가 판매 상품이 최소 하나 선택되어 있는지 확인하세요
할인 값이 유효한 범위 안에 있는지 확인하세요

유효한 캠페인 구조

{
  "name": "Summer Upsell",
  "active": true,
  "products": ["gid://shopify/Product/123"],
  "discount": {
    "type": "percentage",
    "value": 20
  },
  "targeting": {
    "minCartValue": 50
  }
}

COS-2002: 상품을 찾을 수 없음

원인: 캠페인의 상품이 더 이상 존재하지 않거나 사용할 수 없어요.

해결 방법:

Shopify 카탈로그에서 상품이 삭제되었는지 확인하세요
상품이 게시되어 있고 활성 상태인지 확인하세요
유효한 상품 ID로 캠페인을 업데이트하세요

COS-2003: 타기팅 규칙 충돌

원인: 캠페인 타기팅 규칙이 서로 모순돼요.

해결 방법:

타기팅 규칙의 AND/OR 논리를 검토하세요
최솟값과 최댓값이 잘못 겹치지 않는지 확인하세요
장바구니 > US$100이면서 장바구니 < US$50인 경우처럼 불가능한 조건을 확인하세요

결제 오류(COS-3XXX)

COS-3001: 할인 적용 실패

원인: 추가 판매 상품에 할인을 적용할 수 없어요.

해결 방법:

충돌하는 Shopify 할인 코드가 있는지 확인하세요
Shopify의 할인 조합 설정을 확인하세요
상품이 할인 대상에서 제외되지 않았는지 확인하세요

COS-3002: 결제 처리 오류

원인: 추가 판매 상품 대금을 고객에게 청구할 수 없어요.

해결 방법:

일반적으로 Shopify 결제 게이트웨이 문제예요
Shopify Admin → Settings → Payments에서 게이트웨이 상태를 확인하세요
고객이 다른 결제 수단으로 다시 시도해야 할 수 있어요

결제 오류

CheckoutOS는 결제 정보를 저장하지 않아요. 결제 오류는 Shopify의 안전한 결제 인프라를 통해 처리돼요. 상세 결제 로그는 Shopify에서 확인하세요.

COS-3003: 재고 없음

원인: 추가 판매 상품이 품절되었어요.

해결 방법:

캠페인 설정에서 재고 추적 대체 동작을 활성화하세요
품절 상황에 대비해 대체 상품을 설정하세요
적절한 경우 Shopify에서 "Continue selling when out of stock"을 설정하세요

API 오류(COS-4XXX)

COS-4001: 잘못된 API 키

원인: API 요청에 유효하지 않거나 만료된 키를 사용했어요.

해결 방법:

Dashboard → Settings → API에서 API 키를 다시 생성하세요
키에 오타나 공백이 있는지 확인하세요
키에 필요한 권한이 있는지 확인하세요

COS-4002: 요청 한도 초과

원인: 짧은 시간에 API 요청이 너무 많아요.

해결 방법:

애플리케이션에 요청 속도 제한을 구현하세요
반복 조회 대신 웹훅 이벤트를 사용하세요
더 높은 요청 한도가 필요하면 지원팀에 문의하세요

요청 한도 헤더

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642345678
Retry-After: 60

COS-4003: 잘못된 웹훅 서명

원인: 웹훅 서명 검증에 실패했어요.

해결 방법:

웹훅 시크릿이 Dashboard → Settings → API의 값과 일치하는지 확인하세요
서명 검증에 원시 요청 본문을 사용하는지 확인하세요
서버 시계가 동기화되어 있는지 확인하세요

확장 기능 오류(COS-5XXX)

COS-5001: 확장 기능 로드 실패

원인: 브라우저에서 결제 확장 기능을 로드할 수 없어요.

해결 방법:

브라우저 콘솔에서 JavaScript 오류를 확인하세요
광고 차단기나 개인정보 보호 확장 프로그램을 일시적으로 비활성화하세요
브라우저 캐시를 삭제하고 다시 시도하세요
다른 브라우저에서 테스트하세요

COS-5002: 확장 기능 렌더링 오류

원인: 확장 기능은 로드되었지만 올바르게 렌더링되지 않았어요.

해결 방법:

맞춤 CSS 충돌이 있는지 확인하세요
이미지 URL이 유효하고 접근 가능한지 확인하세요
확장 기능 설정에 잘못된 값이 있는지 검토하세요

도움이 더 필요하신가요?

자주 묻는 질문

자주 묻는 질문에 대한 답변

지원팀 문의

지원팀의 맞춤 도움을 받아요