오류 코드

​

개요

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

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

​

표준 API 오류 코드

​

오류 응답 형식

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

​

오류 코드 참조

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

​

모범 사례

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

​

지원