오류 코드

이 페이지에서는 범용 커머스 프로토콜(UCP)을 사용하여 Google과 통합할 때 API 응답에서 반환해야 하는 표준 오류 코드를 간략하게 설명합니다. 일관된 오류 코드는 명확한 커뮤니케이션을 보장하고 Google이 다양한 시나리오를 적절하게 처리하는 데 도움이 됩니다.

비즈니스 오류가 발생하면 API는 표에서 적절한 code를 포함하는 응답 메시지를 반환해야 합니다. 일부 오류 코드의 경우 응답의 messages 배열에 특정 JSON 구조를 사용하는 것이 좋습니다. 이러한 예는 표 아래의 오류 코드 예 섹션 에 제공됩니다. 이러한 예에서는 path 필드를 사용하여 요청 또는 응답 객체 내에서 오류의 위치에 관한 더 구체적인 정보를 제공해야 합니다.

오류 처리

오류를 보고하는 방법은 오류 유형에 따라 다릅니다.

  • 프로토콜/서버 오류:

    • 잘못된 형식의 요청, 인증 실패 또는 서버 사용 불가와 같은 문제에는 표준 HTTP 상태 코드 (예: 클라이언트 오류의 경우 4xx, 서버 오류의 경우 5xx)를 사용합니다.
    • 자세한 내용은 UCP 사양 을 참조하세요.

  • 비즈니스 로직 오류/경고:

    • HTTP 200 OK 상태를 반환합니다. 다운스트림 결제 게이트웨이가 4xx 또는 5xx 오류를 반환하더라도 결제 거부 및 사기 거부가 포함됩니다.
    • JSON 응답 본문의 messages 배열 내에서 문제를 설명합니다.
    • messages 배열의 각 객체에는 다음이 포함되어야 합니다.
      • type: "error" 또는 "warning"
      • code: 이 가이드의 표준화된 코드입니다. 일반 또는 인식할 수 없는 코드(예: "invalid")는 사용하지 마세요.
      • content: 사람이 읽을 수 있는 설명입니다.
      • severity: type이 "error"인 경우 필수입니다. 이 필드는 오류 코드 자체에 의존하는 대신 오류가 터미널 (unrecoverable)인지 명시적으로 나타내거나 구매자에게 문제를 수정하도록 (recoverable) 메시지를 표시할 수 있습니다.

메시지 유형: 오류와 경고

메시지 배열의 type 필드는 문제의 심각도를 나타냅니다. UCP는 두 가지 기본 유형을 정의합니다.

  • error: 요청된 작업을 완료할 수 없음을 나타냅니다. 플랫폼 또는 사용자가 조치를 취하고 다시 시도해야 할 수 있습니다. message-error 사양을 참고하세요.
    • 오류의 터미널 특성은 severity 필드 (unrecoverable 또는 recoverable)에 의해 결정됩니다. 오류 code가 아닙니다.
  • warning: 작업이 차단되지 않았지만 사용자에게 전달해야 할 주목할 만한 사항이 있음을 나타냅니다. 이로 인해 프로세스가 중단되지는 않지만 중요한 컨텍스트가 제공됩니다. message-warning 사양을 참고하세요.

오류 코드 참조

오류 코드 권장 유형 설명
out_of_stock 오류 상품을 구매할 수 없습니다. 일반적으로 ucp.status: “error”가 발생합니다. path 필드를 사용하여 여러 상품 결제에서 상품 색인을 나타냅니다. 아래 예를 참고하세요.
item_unavailable 오류 상품을 찾을 수 없습니다. 일반적으로 이러한 상품 관련 오류에 대해 ucp.status: “error”가 발생합니다.
item_ineligible 오류 상품이 있지만 UCP를 사용하여 구매할 수 없습니다.
quantity_invalid_limit_exceeded 오류 요청된 수량이 허용 한도를 초과합니다. 아래 예를 참고하세요.
quantity_invalid_minimum_not_met 오류 요청된 수량이 최소 요구사항보다 적습니다.
totals_changed 주의 마지막 단계 이후 가격 또는 기타 합계가 변경되었습니다. path 필드를 사용하여 변경된 합계를 나타냅니다. 아래 예를 참고하세요.
totals_invalid_minimum_not_met 오류 주문 금액이 최소 요구사항을 충족하지 않습니다.
missing_buyer_info 오류 필수 구매자 정보가 누락되었습니다. path 필드를 사용하여 누락된 필드를 지정합니다. 아래 예를 참고하세요.
address_undeliverable 오류 표준 UCP 오류 코드입니다. path 필드를 사용하여 특정 대상 또는 제한된 상품을 나타냅니다. 아래 예를 참고하세요.
address_unverifiable 오류 제공된 주소를 확인할 수 없습니다. path 필드를 사용하여 처리 주소인지 청구서 수신 주소인지 나타냅니다. 아래 예를 참고하세요.
missing_fulfillment_info 오류 필수 처리 정보가 누락되었습니다. path 필드를 사용하여 누락된 필드를 지정합니다.
eligibility_invalid 오류 사용자 또는 주문이 작업에 적합하지 않습니다. 표준 UCP 오류 코드입니다. 구체적인 내용은 path 필드를 사용하세요.
discount_code_invalid 주의 할인 코드가 잘못되었습니다. 코드를 찾을 수 없거나 형식이 잘못되었습니다.
discount_code_expired 주의 할인 코드가 만료되었습니다.
discount_code_already_applied 주의 할인 코드가 이미 적용되었습니다.
discount_code_combination_disallowed 주의 할인 코드는 다른 혜택과 함께 사용할 수 없습니다.
discount_code_user_not_logged_in 주의 할인 코드를 사용하려면 사용자가 로그인해야 합니다.
discount_code_user_ineligible 주의 사용자가 할인 코드를 사용할 수 없습니다.
missing_billing_info 오류 필수 결제 정보가 누락되었습니다. path 필드를 사용하여 누락된 청구서 수신 주소 필드를 지정합니다. 아래 예를 참고하세요.
identity_required 오류 요청된 작업에 사용자 ID가 필요하지만 없거나, 잘못되었거나, 만료되었거나, 확인할 수 없습니다. REST의 경우 상태 코드 401을 사용합니다. 아래 예를 참고하세요.
insufficient_scope 오류 사용자 ID 토큰은 유효하지만 작업에 필요한 범위가 없습니다. REST의 경우 상태 코드 403을 사용합니다. 아래 예를 참고하세요.
payment_declined 오류 카드 발급기관 또는 은행에서 결제를 거부했습니다. 이유로는 잔액 부족, 사기 의심 또는 카드 문제 등이 있습니다. 아래 예를 참고하세요.
payment_failed 오류 처리 중 네트워크 오류, 게이트웨이 시간 초과 또는 통합 문제와 같은 기술적 문제로 인해 결제가 실패하여 은행에서 결정을 내릴 수 없었습니다.
payment_ineligible 오류 선택한 결제 수단이 허용되지 않습니다. 사용자가 다른 결제 수단을 사용해 봐야 하는 경우에 적합합니다.
rejected_for_fraud 오류 사기 의심으로 인해 주문이 거부되었습니다. 아래 예를 참고하세요.

오류 코드 예

이 섹션에서는 특정 오류 코드의 messages 배열에 관한 JSON 예를 제공합니다.

out_of_stock

단일 상품 결제:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

여러 상품 결제:

path 필드를 사용하여 재고가 없는 특정 항목의 색인을 나타냅니다.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

주문 수준 제한 (예: 우편번호 지원되지 않음):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

상품 수준 제한:

path 필드를 사용하여 선택한 대상에 배송할 수 없는 특정 상품 (예: 주별 금지)을 나타냅니다.

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

청구서 수신 주소:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

처리 주소:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

path 필드를 사용하여 청구서 수신 주소 내에서 누락된 필드를 지정합니다.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

REST API에서 이 오류는 HTTP 상태 코드 401과 함께 반환되어야 합니다.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

REST API에서 이 오류는 HTTP 상태 코드 403과 함께 반환되어야 합니다.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

결제 오류

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}