---
title: "오류 코드: CheckoutOS 문서 | Chargezen"
description: "CheckoutOS 오류 코드와 해결 방법 참조. Chargezen CheckoutOS 문서의 문제 해결 섹션에 있어요."
url: "https://chargezen.com/ko/docs/checkoutos/troubleshooting/error-codes"
lang: "ko"
updated: "2025-01-16"
---

Canonical URL: https://chargezen.com/ko/docs/checkoutos/troubleshooting/error-codes

# 오류 코드

CheckoutOS 오류 코드와 해결 방법 참조

마지막 업데이트: 2025-01-16

이 참조 문서는 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: 잘못된 캠페인 설정

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

**해결 방법:**

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

유효한 캠페인 구조

```json
{
  "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 요청이 너무 많아요.

**해결 방법:**

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

요청 한도 헤더

```text
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이 유효하고 접근 가능한지 확인하세요
*   확장 기능 설정에 잘못된 값이 있는지 검토하세요

## 도움이 더 필요하신가요?

[

### 자주 묻는 질문

자주 묻는 질문에 대한 답변

자세히 보기



](https://chargezen.com/ko/docs/checkoutos/troubleshooting/faq)[

### 지원팀 문의

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

자세히 보기



](https://chargezen.com/ko/docs/checkoutos/troubleshooting/support)

이 페이지가 도움이 되었나요?

도움이 더 필요하신가요? [고객 지원 문의](https://chargezen.com/ko/docs/checkoutos/troubleshooting/support)