이 페이지는 Cloud Translation API를 통해 번역되었습니다.

오류 응답 처리

이 가이드에서는 Merchant API에서 반환된 오류를 처리하는 방법을 설명합니다. 오류 응답 구조와 안정성을 이해하는 것은 실패로부터 자동으로 복구되거나 사용자에게 의미 있는 피드백을 제공할 수 있는 강력한 통합을 빌드하는 데 중요합니다.

개요

Merchant API 요청이 실패하면 API는 표준 HTTP 상태 코드(4xx 또는 5xx)와 오류에 관한 세부정보가 포함된 JSON 응답 본문을 반환합니다. Merchant API는 오류 세부정보에 AIP-193 표준을 따르므로 애플리케이션이 특정 오류 시나리오를 프로그래매틱 방식으로 처리할 수 있는 머신 리더블 정보를 제공합니다.

오류 응답 구조

오류 응답은 code, message, status과 같은 표준 필드가 포함된 JSON 객체입니다. 중요한 점은 details 배열도 포함된다는 것입니다. 오류를 프로그래매틱 방식으로 처리하려면 @type이 type.googleapis.com/google.rpc.ErrorInfo인 details 내에서 객체를 찾아야 합니다.

이 ErrorInfo 객체는 오류에 관한 안정적인 구조화된 데이터를 제공합니다.

domain: 오류의 논리적 그룹입니다. 일반적으로 merchantapi.googleapis.com입니다.
metadata: 오류와 관련된 동적 값의 맵입니다. 여기에는 다음이 포함됩니다.
- REASON: 정확한 오류의 구체적이고 안정적인 식별자입니다 (예: INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS)입니다. 이 필드는 항상 표시됩니다. 애플리케이션 로직에서 세부적인 오류 처리를 위해 이 필드를 사용하세요.
- HELP_CENTER_LINK: 문제를 해결하기 위한 추가 컨텍스트와 안내를 제공합니다. 이 필드는 일부 오류에만 표시되지만, 더 많은 컨텍스트가 필요할 수 있는 오류에 대해 적용 범위를 확대할 계획입니다.
- 기타 동적 필드: 잘못된 필드 이름 (FIELD_LOCATION) 또는 오류를 일으킨 값 (FIELD_VALUE)과 같은 컨텍스트를 제공하는 기타 키입니다.

샘플 오류 응답

다음 JSON은 리소스 이름이 잘못된 Merchant API 오류의 구조를 보여줍니다.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

다음은 인증 오류의 예입니다.

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

오류 필드의 안정성

오류 처리 로직을 작성할 때는 신뢰할 수 있는 필드와 변경될 수 있는 필드를 아는 것이 중요합니다.

안정적인 필드:
details.metadata.REASON: 특정 오류 식별자입니다. 애플리케이션의 제어 흐름 로직에 이 필드를 사용해야 합니다.
- details.metadata 키: 메타데이터 맵 내의 키입니다 (예: FIELD_LOCATION, ACCOUNT_IDS)이 안정화되었습니다.
- code: 상위 수준 HTTP 상태 코드입니다 (예: 400, 401, 503)이 안정화되었습니다.
불안정한 필드:
- message: 사람이 읽을 수 있는 오류 메시지가 안정적이지 않습니다. 이 옵션은 개발자 디버깅 전용입니다. 명확성을 개선하거나 맥락을 추가하기 위해 사전 통지 없이 변경될 수 있으므로 message 필드의 텍스트 콘텐츠를 파싱하거나 이에 의존하는 코드를 작성하지 마세요.
- details.metadata 값: 키는 안정적이지만 정보 키의 값은 변경될 수 있습니다. 예를 들어 HELP_CENTER_LINK 키가 제공된 경우 이 키가 가리키는 특정 URL이 사전 알림 없이 최신 문서 페이지로 업데이트될 수 있습니다. 하지만 앞에서 언급한 것처럼 details.metadata.REASON 값은 안정적입니다.

권장사항

통합에서 오류를 적절하게 처리하려면 다음 권장사항을 따르세요.

로직에 `details.metadata.REASON` 사용

항상 metadata 맵 내에서 특정 REASON을 사용하여 오류 원인을 확인하세요. 여러 오류가 동일한 상태 코드를 공유할 수 있으므로 HTTP 상태 코드만 사용하지 마세요.

오류 메시지를 파싱하지 않음

안정성 섹션에서 설명한 대로 message 필드는 사람이 소비하기 위한 것입니다. 잘못된 필드와 같은 동적 정보가 필요한 경우 FIELD_LOCATION, VARIABLE_NAME와 같은 안정적인 키를 사용하여 metadata 맵에서 정보를 추출합니다.

지수 백오프 구현

일시적인 사용 불가능 또는 비율 제한을 나타내는 오류의 경우 지수 백오프 전략을 구현합니다. 즉, 재시도하기 전에 잠시 기다리고 이후 실패할 때마다 대기 시간을 늘립니다.

quota/request_rate_too_high: 이 오류는 특정 할당량 그룹의 분 할당량을 초과했음을 나타냅니다. 요청 속도를 낮추세요.
internal_error: 일반적으로 일시적입니다. 지수 백오프로 다시 시도합니다. 참고: 지연을 사용하여 여러 번 재시도한 후에도 internal_error가 지속되면 Merchant API 지원팀에 문의하는 방법을 참고하세요.

Merchant API 지원팀에 문의하는 방법

특정 오류에 관해 Merchant API 지원팀에 문의해야 하는 경우 요청에 다음 정보를 제공하세요.

수신된 정확한 오류 응답
API 메서드 이름
요청 페이로드
메서드가 호출되고 오류가 수신된 타임스탬프 또는 기간