API 오류 이해

이 가이드에서는 Google Ads API가 오류를 처리하고 전달하는 방법을 설명합니다. API 오류의 구조와 의미를 이해하는 것은 잘못된 입력부터 일시적인 서비스 사용 불가에 이르기까지 문제를 원활하게 처리할 수 있는 강력한 애플리케이션을 빌드하는 데 매우 중요합니다.

Google Ads API는 gRPC 상태 코드를 기반으로 하는 표준 Google API 오류 모델을 따릅니다. 오류가 발생하는 각 API 응답에는 다음이 포함된 Status 객체가 포함됩니다.

• 숫자 오류 코드
• 오류 메시지
• 추가 오류 세부정보(선택사항)

표준 오류 코드

Google Ads API는 gRPC 및 HTTP에서 정의한 표준 오류 코드 집합을 사용합니다. 이러한 코드는 오류 유형을 대략적으로 나타냅니다. 문제의 근본적인 특성을 이해하려면 항상 이 숫자 코드를 먼저 확인해야 합니다.

다음 표에는 Google Ads API를 사용할 때 발생할 수 있는 가장 일반적인 코드가 요약되어 있습니다.

이러한 코드에 관한 자세한 내용은 API 디자인 가이드 - 오류 코드를 참고하세요.

오류 세부정보 이해하기

최상위 코드 외에도 Google Ads API는 Status 객체의 details 필드 내에서 더 구체적인 오류 정보를 제공합니다. 이 필드에는 개별 GoogleAdsError 객체 목록이 포함된 GoogleAdsFailure 프로토가 포함되는 경우가 많습니다.

각 GoogleAdsFailure 객체에는 다음이 포함됩니다.

• errors: 발생한 특정 오류를 자세히 설명하는 GoogleAdsError 객체 목록입니다.
• request_id: 디버깅 및 지원 목적으로 유용한 요청의 고유 ID입니다.

각 GoogleAdsError 객체는 다음을 제공합니다.

• errorCode: Google Ads API별 오류 코드와 같은 더 상세한 오류 코드입니다AuthenticationError.NOT_ADS_USER.
• message: 사람이 읽을 수 있는 특정 오류 설명입니다.
• trigger: 오류를 일으킨 값입니다(해당하는 경우).
• location: 필드 경로를 포함하여 요청에서 오류가 발생한 위치를 설명합니다.
• details: 게시되지 않은 오류 사유와 같은 추가 오류 세부정보입니다.

오류 세부정보의 예

오류가 발생하면 클라이언트 라이브러리를 통해 이러한 세부정보에 액세스할 수 있습니다. 예를 들어 INVALID_ARGUMENT (코드 3)에는 다음과 같은 GoogleAdsFailure 세부정보가 있을 수 있습니다.

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

이 예에서는 최상위 INVALID_ARGUMENT에도 불구하고 GoogleAdsFailure 세부정보를 통해 name 및 description 필드가 문제를 일으킨 이유 (REQUIRED 및 TOO_SHORT, 각각)를 알 수 있습니다.

오류 세부정보 찾기

오류 세부정보에 액세스하는 방법은 표준 API 호출, 부분 실패 또는 스트리밍을 사용하는지에 따라 다릅니다.

표준 및 스트리밍 API 호출

스트리밍 호출을 포함하여 부분 실패를 사용하지 않고 API 호출이 실패하면 GoogleAdsFailure 객체가 gRPC 응답 헤더의 후행 메타데이터의 일부로 반환됩니다. 표준 호출에 REST를 사용하는 경우 GoogleAdsFailure가 HTTP 응답으로 반환됩니다. 클라이언트 라이브러리는 일반적으로 속성이 있는 예외로 이를 표시합니다. GoogleAdsFailure

부분 실패

부분 실패를 사용하는 경우 실패한 작업의 오류는 응답 헤더가 아닌 응답의 partial_failure_error 필드에 반환됩니다. 이 경우 GoogleAdsFailure는 응답의 google.rpc.Status 객체 내에 삽입됩니다.

일괄 작업

일괄 처리의 경우 작업이 완료된 후 일괄 작업 결과를 가져와 개별 작업의 오류를 찾을 수 있습니다. 작업이 실패하면 각 작업 결과에 오류 세부정보가 포함된 status 필드가 포함됩니다.

요청 ID

request-id는 API 요청을 식별하는 고유한 문자열로, 문제 해결에 필수적입니다.

여러 곳에서 request-id를 찾을 수 있습니다.

• GoogleAdsFailure: API 호출이 실패하고 GoogleAdsFailure가 반환되면 request_id가 포함됩니다.
• 후행 메타데이터: 성공한 요청과 실패한 요청 모두에 대해 request-id 은 gRPC 응답의 후행 메타데이터에서 사용할 수 있습니다.
• 응답 헤더: 성공한 요청과 실패한 요청 모두에 대해 request-id는 성공한 스트리밍 요청을 제외하고 gRPC 및 HTTP 응답 헤더에서도 사용할 수 있습니다.
• SearchGoogleAdsStreamResponse: 스트리밍 요청의 경우 각 SearchGoogleAdsStreamResponse 메시지에는 request_id 필드가 포함됩니다.

오류를 로깅하거나 지원팀에 문의할 때는 문제 진단에 도움이 되도록 request-id를 포함해야 합니다.

오류 처리 권장사항

복원력이 뛰어난 애플리케이션을 빌드하려면 다음 권장사항을 구현하세요.

1. 오류 세부정보 검사: 항상 details 필드를 파싱하고 특히 Status 객체에서 GoogleAdsFailure를 찾습니다. 세분화된 errorCode, message, location 내의 GoogleAdsError은 디버깅 및 사용자 의견에 가장 유용한 정보를 제공합니다.

2. 클라이언트 오류와 서버 오류 구분:

   • 클라이언트 오류: INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED와 같은 코드입니다. 이러한 오류에는 요청 또는 애플리케이션의 상태/사용자 인증 정보를 변경해야 합니다. 문제를 해결하지 않은 상태로 요청을 다시 시도하지 마세요.
   • 서버 오류: UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN과 같은 코드입니다. 이는 API 서비스에 일시적인 문제가 있음을 나타냅니다.

3. 재시도 전략 구현:

   • 재시도 시점: 일시적인 서버 오류( UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, ABORTED)에 대해서만 다시 시도합니다.
   • 지수 백오프: 지수 백오프 알고리즘을 사용하여 재시도 간 대기 시간을 늘립니다. 이렇게 하면 이미 스트레스를 받고 있는 서비스에 과부하가 걸리지 않도록 할 수 있습니다. 예를 들어 1초, 2초, 4초 동안 기다린 후 최대 재시도 횟수 또는 총 대기 시간까지 계속합니다.
   • 지터: 많은 클라이언트가 동시에 다시 시도하는 'thundering herd' 문제를 방지하기 위해 백오프 지연에 작은 임의의 '지터'를 추가합니다.

4. 철저한 로깅: 모든 세부정보, 특히 요청 ID를 포함하여 전체 오류 응답을 로깅합니다. 이 정보는 디버깅 및 필요한 경우 Google 지원팀에 문제를 신고하는 데 필수적입니다.

5. 사용자 의견 제공: 특정 GoogleAdsError 코드 및 메시지를 기반으로 애플리케이션 사용자에게 명확하고 유용한 의견을 제공합니다. 예를 들어 '오류가 발생했습니다'라고만 말하는 대신 '캠페인 이름이 필요합니다' 또는 '제공된 광고그룹 ID를 찾을 수 없습니다'라고 말할 수 있습니다.

이 가이드라인을 따르면 Google Ads API에서 반환된 오류를 효과적으로 진단하고 처리하여 더 안정적이고 사용자 친화적인 애플리케이션을 만들 수 있습니다.