오류 코드

​

개요

• 오류의 일반적인 범주를 나타내는 HTTP 상태 코드
• 오류의 정확한 성격을 식별하는 특정 오류 코드
• 무엇이 잘못되었는지 설명하는 사람이 읽을 수 있는 오류 메시지
• 해당하는 경우 오류에 대한 추가 세부정보

• 통합 문제 디버깅
• 애플리케이션에서 적절한 오류 처리 구현
• 최종 사용자에게 의미 있는 피드백 제공
• 강력한 결제 처리 시스템 유지

​

표준 API 오류 코드

​

오류 응답 형식

{
  "code": "UNSUPPORTED_COUNTRY",
  "message": "Country AI currently not supported"
}

​

오류 코드 참조

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • 트리거: 라이센스 키 활성화: 새 한도 < 기존 인스턴스 수
  • 메시지: 새 활성화 한도는 현재 인스턴스 수보다 작을 수 없습니다.
• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • 트리거: 사용 기반 청구 구독에 추가 애드온을 추가하려고 시도
  • 메시지: 구독의 애드온은 사용 기반 청구를 지원하지 않습니다.
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • 트리거: 주문형 구독에 애드온을 추가하려고 시도
  • 메시지: 주문형 구독에는 애드온이 허용되지 않습니다.
• BRAND_MISMATCH
  • 트리거: 장바구니 항목이 서로 다른 브랜드에 속함
  • 메시지: 제품 장바구니의 모든 항목은 동일한 브랜드에 속해야 합니다.
• BRAND_NOT_ENABLED
  • 트리거: 브랜드가 비활성화되었거나 활성 상태가 아님
  • 메시지: 제공된 브랜드가 활성화되지 않았습니다.
• BRAND_SUBMISSION_NOT_ENABLED
  • 트리거: 브랜드 검증 재제출 기능이 활성화되지 않음
  • 메시지: 브랜드 검증 재제출이 활성화되지 않았습니다.
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • 트리거: 취소 예정인 구독에 대해 요금을 청구하려고 시도
  • 메시지: 취소 예정인 구독입니다.
• CHECKOUT_SESSION_CONSUMED
  • 트리거: 체크아웃 세션이 이미 결제를 생성함
  • 메시지: 체크아웃 세션이 이미 사용되었습니다.
• DISCOUNT_CODE_ALREADY_EXISTS
  • 트리거: 중복 할인 코드 생성
  • 메시지: 할인 코드가 이미 존재합니다.
• DISCOUNT_CODE_EXPIRED
  • 트리거: 할인 코드가 expires_at 날짜를 초과함
  • 메시지: 할인 코드가 만료되었습니다.
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • 트리거: usage_limit에 도달한 후 할인 재사용
  • 메시지: 사용 한도는 times_used / 할인 코드 사용 한도보다 작을 수 없습니다.
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • 트리거: 주문형 구독에 적용된 코드
  • 메시지: 할인 쿠폰은 주문형 구독에 사용할 수 없습니다.
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • 트리거: 관련 없는 제품에 적용된 코드
  • 메시지: 할인 쿠폰은 이 제품에 사용할 수 없습니다.
• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • 트리거: 동일한 item_id가 items[]에 두 번 나타남
  • 메시지: 항목 배열에 중복 item_ids가 지정되었습니다.
• DUPLICATE_METER_IDS_IN_REQUEST
  • 트리거: 요청에 동일한 미터 ID가 여러 번 나타남
  • 메시지: 중복 미터 ID는 허용되지 않습니다.
• EXCHANGE_RATE_NOT_FOUND
  • 트리거: from → to 통화 쌍에 대한 FX 환율 없음
  • 메시지: 통화에서 통화로 변환할 환율을 찾을 수 없습니다.
• EXISTING_REFUND_REQUEST_PROCESSING
  • 트리거: 이전 환불 요청이 여전히 처리 중
  • 메시지: 상태가 “대기 중”인 환불 요청이 여전히 처리 중입니다.
• INACTIVE_LICENSE_KEY
  • 트리거: 키 상태 ≠ ACTIVE
  • 메시지: 라이센스 키가 활성화되지 않았습니다.
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • 트리거: 비활성 구독에서 계획 변경
  • 메시지: 비활성 구독에 대해 계획 변경이 지원되지 않습니다.
• INSUFFICIENT_WALLET_FUNDS
  • 트리거: 지갑 잔액 < 인출 금액
  • 메시지: 지갑에 충분한 자금이 없습니다.
• INTEGER_CONVERSION_FAILURE
  • 트리거: 서버 측에서 실패한 모든 정수 ↔ 문자열/소수 변환
  • 메시지: 정수 변환 실패
• INTERNAL_SERVER_ERROR
  • 트리거: 포착되지 않은 예외; 서버 측에서 세부정보를 기록해야 합니다.
  • 메시지: 공식 메시지 없음 (일반 500)
• INVALID_DISCOUNT_CODE
  • 트리거: 코드가 존재하지 않음 / 적용할 수 없음
  • 메시지: 유효하지 않은 할인 코드 / 할인 코드를 장바구니의 어떤 제품에도 적용할 수 없습니다.
• INVALID_PERCENTAGE
  • 트리거: 비율 금액 > 100% (또는 10,000 기준 포인트)
  • 메시지: 비율 금액은 10000을 초과할 수 없습니다 / 할인 코드 금액은 100%를 초과할 수 없습니다.
• INVALID_QUANTITY
  • 트리거: 사용 기반 가격 책정에 대해 지정된 수량이 유효하지 않음
  • 메시지: 사용 기반 가격 제품에서는 1개 수량만 허용됩니다.
• INVALID_QUERY_PARAMS
  • 트리거: 상호 배타적 / 잘못된 쿼리 매개변수
  • 메시지: 쿼리 매개변수는 time_frame 또는 (start, end) 중 하나만 포함해야 합니다.
• INVALID_REQUEST_BODY
  • 트리거: 잘못된 JSON 또는 스키마 위반
  • 메시지: 요청 본문이 유효하지 않습니다. 요청 헤더와 객체를 확인하십시오.
• INVALID_REQUEST_PARAMETERS
  • 트리거: 의미론적으로 잘못됨 (예: 과거 날짜)
  • 메시지: next_billing_date를 과거 시간으로 변경할 수 없습니다.
• INVALID_SUGGESTED_PRICE
  • 트리거: PWYW 가격 < 최소 허용 가격
  • 메시지: 제안된 가격은 최소 가격보다 낮을 수 없습니다. 원하는 만큼 지불하는 경우 가격은 최소 수락 금액으로 간주됩니다.
• INVALID_TAX_ID
  • 트리거: VAT/GST/TIN 유효성 검사 실패
  • 메시지: 세금 ID가 유효하지 않습니다.
• LICENSE_KEY_LIMIT_REACHED
  • 트리거: 활성화 = 한도
  • 메시지: 라이센스 키 활성화 한도에 도달했습니다.
• LICENSE_KEY_NOT_FOUND
  • 트리거: 인스턴스 ID 또는 키 ID가 유효하지 않음
  • 메시지: 라이센스 키 인스턴스를 찾을 수 없거나 이 라이센스 키에 속하지 않습니다.
• LINE_ITEM_FULLY_REFUNDED
  • 트리거: 이미 완전히 환불된 항목에 대해 환불을 시도
  • 메시지: 항목 는 이미 완전히 환불되었으므로 추가 환불이 불가능합니다.
• LINE_ITEM_NOT_FOUND
  • 트리거: 참조된 결제의 일부가 아닌 항목 ID
  • 메시지: 항목 가 결제에서 발견되지 않았습니다.
• LINE_ITEM_PRORATED
  • 트리거: 비례 항목에 대해 환불 또는 업데이트 시도
  • 메시지: 항목 는 비례적이므로 환불할 수 없습니다.
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • 트리거: 환불 금액 > 지불 금액 (세금 포함)
  • 메시지: 항목 의 요청된 환불 금액(세금 포함)은 로, 지불 금액 를 초과합니다.
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • 트리거: 최소 임계값 이하의 환불 금액
  • 메시지: 항목 의 요청된 환불 금액은 로 너무 낮습니다.
• MAXIMUM_KEYS_REACHED
  • 트리거: 메타데이터 / 사용자 정의 필드가 50 쌍을 초과함
  • 메시지: 50개 키-값 쌍을 초과했습니다.
• MERCHANT_NOT_LIVE
  • 트리거: 비즈니스가 여전히 테스트/샌드박스 모드에 있음
  • 메시지: 상인이 라이브 상태가 아닙니다.
• METER_IS_DELETED
  • 트리거: 삭제된 미터를 사용하려고 시도
  • 메시지: 미터가 이미 삭제되었습니다.
• MISSING_ADDON_IDS
  • 트리거: addon_id 목록이 비어 있거나 알 수 없는 ID
  • 메시지: 하나 이상의 제품 ID가 존재하지 않습니다:
• MISSING_METER_IDS
  • 트리거: 미터 ID 목록이 비어 있거나 유효하지 않은 ID 포함
  • 메시지: 하나 이상의 미터 ID가 존재하지 않습니다:
• MISSING_PRODUCT_INFORMATION
  • 트리거: 제품이 존재하지만 필수 정보가 누락됨
  • 메시지: 제품 가 존재하지만 다른 필수 정보가 누락되었거나 유효하지 않습니다.
• NEGATIVE_BALANCE_ADJUSTMENT
  • 트리거: 지갑 잔액을 음수로 만들려고 시도
  • 메시지: 지갑 잔액을 음수로 만들 수 없습니다.
• NO_ELIGIBLE_PAYMENT_METHODS
  • 트리거: 필터링 후 남은 것이 없음
  • 메시지: 적격 결제 방법을 찾을 수 없습니다.
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • 트리거: 구독 기반 키에 만료를 설정하려고 시도
  • 메시지: 구독 기반 라이센스 키에 대해 만료 날짜를 설정할 수 없습니다.
• NOT_FOUND
  • 트리거: 누락된 리소스에 대한 일반 404
  • 메시지: 항목을 찾을 수 없습니다 (또는 더 구체적)
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • 트리거: 주문형에 대한 계획 변경이 허용되지 않음
  • 메시지: 주문형 구독에 대한 계획 변경이 지원되지 않습니다.
• ON_DEMAND_SUBSCRIPTIONS_NOT_ENABLED
  • 트리거: 비즈니스에 기능 플래그가 꺼져 있음
  • 메시지: 이 비즈니스에 대해 주문형 구독이 활성화되지 않았습니다.
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • 트리거: 사용 기반 청구와 함께 주문형 사용 시도
  • 메시지: 사용 기반 청구에 대해 주문형 구독이 지원되지 않습니다.
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • 트리거: PWYW 제품에 대한 가격 누락
  • 메시지: 원하는 만큼 지불하는 제품에 대한 금액은 필수입니다.
• PAYMENT_ALREADY_REFUNDED
  • 트리거: 중복 환불
  • 메시지: 이 결제는 이미 환불되었습니다.
• PAYMENT_HAS_BEEN_REFUNDED
  • 트리거: 결제가 완전히 환불됨
  • 메시지: 결제 ID가 완전히 환불되었습니다.
• PAYMENT_NOT_SUCCEEDED
  • 트리거: 실패한 결제를 환불/처리하려고 시도
  • 메시지: 제공된 결제가 성공하지 않았습니다.
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • 트리거: 취소 예정인 구독에서 계획 변경 시도
  • 메시지: 취소 예정인 구독입니다.
• PREVIOUS_PAYMENT_PENDING
  • 트리거: 이전 결제가 비종료 상태인 동안 요금을 생성하려고 시도
  • 메시지: 이전 결제가 아직 성공하지 않았으므로 새 요금을 생성할 수 없습니다.
• PRODUCT_CART_EMPTY
  • 트리거: 제출된 제품 장바구니가 비어 있음
  • 메시지: product_cart가 비어 있습니다.
• PRODUCT_IS_DELETED
  • 트리거: 제품이 소프트 삭제됨
  • 메시지: 메시지 없음
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • 트리거: 집계 환불 금액 > 지불 금액
  • 메시지: 계산된 환불 금액이 지불 금액보다 큽니다.
• REFUND_WINDOW_EXPIRED
  • 트리거: 허용된 환불 기간 외부
  • 메시지: 결제 생성 후 일 이내에 환불을 시작할 수 없습니다. [email protected]에 문의하십시오.
• REQUEST_AMOUNT_BELOW_MINIMUM
  • 트리거: 금액 < 제품 최소
  • 메시지: 금액은 제품에 대해 지정된 최소 금액보다 작을 수 없습니다.
• SUBSCRIPTION_EXPIRED
  • 트리거: 청구가 ends_at를 초과함
  • 메시지: 구독이 만료되어 새 요금을 생성할 수 없습니다.
• SUBSCRIPTION_INACTIVE
  • 트리거: 상태 ≠ ACTIVE
  • 메시지: 구독이 활성 상태가 아닙니다.
• SUBSCRIPTION_NOT_ON_DEMAND
  • 트리거: 주문형으로 예상했지만 고정 간격을 받음
  • 메시지: 구독이 이미 주문형이 아닙니다.
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • 트리거: 구독 결제 재시도가 최대 시도를 초과함
  • 메시지: 이 구독에 대해 최대 10회 재시도 한도를 초과했습니다.
• TOO_MANY_REQUESTS
  • 트리거: 429 비율 제한
  • 메시지: 메시지 없음
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • 트리거: 결합된 장바구니 총액 < 게이트웨이 최소
  • 메시지: 결제를 처리하기 위해 의 최소 금액이 필요합니다.
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • 트리거: 일반 API를 통해 기본 브랜드를 업데이트하려고 시도
  • 메시지: 기본 브랜드는 이 API 엔드포인트를 통해 업데이트할 수 없습니다.
• UNAUTHORIZED
  • 트리거: API 키 없음 또는 유효하지 않은 토큰 / 범위
  • 메시지: 이 작업을 수행할 권한이 없습니다.
• UNSUPPORTED_ACTION
  • 트리거: 리소스 유형에 대한 지원되지 않는 작업
  • 메시지: 사용 기반 구독에 대한 계획 변경은 지원되지 않습니다.
• UNSUPPORTED_BILLING_CURRENCY
  • 트리거: 구독이 USD로 제한됨
  • 메시지: 구독에 대해 비 USD 청구 통화는 지원되지 않습니다.
• UNSUPPORTED_COUNTRY
  • 트리거: 지원되지 않는 지역
  • 메시지: 국가 는 현재 지원되지 않습니다.
• UNSUPPORTED_CURRENCY
  • 트리거: 제품 또는 애드온 통화가 유효하지 않음
  • 메시지: 통화가 현재 지원되지 않음 / 현재 USD 및 INR 제품만 지원됨 / 애드온 가격에 대해서는 현재 USD 및 INR만 지원됨 / 청구 통화에 대해 USD 또는 INR만 요청할 수 있음 / 통화 지원되지 않음 / 인도 카드 구독에 대한 예기치 않은 통화
• UNSUPPORTED_DISCOUNT_TYPE
  • 트리거: 고정 금액 할인 등, 아직 활성화되지 않음
  • 메시지: 현재는 비율 할인 코드만 지원됩니다.
• UNSUPPORTED_PAYMENT_CURRENCY
  • 트리거: 커넥터에 대해 차단된 결제 통화
  • 메시지: 이 거래에 대해 INR 거래는 지원되지 않습니다.
• UNSUPPORTED_TAX_CATEGORY
  • 트리거: 세금 카테고리 문자열이 열거형에 없음
  • 메시지: 카테고리 는 현재 지원되지 않습니다.
• UNSUCCESSFUL_PAYMENT_ID
  • 트리거: 결제 ID가 실패한 결제를 참조함
  • 메시지: 결제 ID가 실패한 상태입니다.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • 트리거: 0 금액 결제를 환불하려고 시도
  • 메시지: 0 통화 금액의 결제를 환불할 수 없습니다.

​

모범 사례

1. 애플리케이션에서 오류를 항상 우아하게 처리하십시오.
2. 적절한 오류 로깅을 구현하십시오.
3. 최종 사용자에게 적절한 오류 메시지를 사용하십시오.
4. 일시적인 오류에 대한 재시도 로직을 구현하십시오.
5. 해결되지 않은 문제에 대해서는 지원팀에 문의하십시오.

​

지원