이 가이드에서는 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)과 같은 컨텍스트를 제공하는 기타 키입니다.
- REASON: 정확한 오류의 구체적이고 안정적인 식별자입니다 (예:
샘플 오류 응답
다음 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 메서드 이름
- 요청 페이로드
- 메서드가 호출되고 오류가 수신된 타임스탬프 또는 시간 범위