API 오류 이해

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

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

숫자 오류 코드입니다.
오류 메시지입니다.
선택사항인 추가 오류 세부정보입니다.

표준 오류 코드

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

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

gRPC 코드	HTTP 코드	열거형 이름	설명	가이드
0	200	`OK`	오류가 없으며 성공을 나타냅니다.	해당 사항 없음
1	499	`CANCELLED`	작업이 취소되었습니다. 대개 클라이언트에 의해 취소됩니다.	일반적으로 클라이언트가 대기를 중지했음을 의미합니다. 클라이언트 측 제한 시간을 확인합니다.
2	500	`UNKNOWN`	알 수 없는 오류가 발생했습니다. 오류 메시지 또는 세부정보에 자세한 내용이 있을 수 있습니다.	서버 오류로 처리합니다. 잠시 시간을 두고 다시 시도할 수 있는 경우가 많습니다.
3	400	`INVALID_ARGUMENT`	클라이언트에서 잘못된 인수를 지정했습니다. 잘못된 리소스 이름이나 잘못된 값과 같이 API가 요청을 처리하지 못하도록 하는 문제가 있음을 나타냅니다.	클라이언트 오류: 요청 매개변수를 검토하여 API 요구사항을 충족하는지 확인합니다. 오류 세부정보에는 일반적으로 어떤 인수가 잘못되었는지와 그 이유에 관한 정보가 제공됩니다. 이러한 세부정보를 사용하여 요청을 수정하세요. 요청을 수정하지 않고 다시 시도하지 마세요.
4	504	`DEADLINE_EXCEEDED`	작업을 완료하기 전에 기한이 지났습니다.	서버 오류: 일시적인 경우가 많습니다. 지수 백오프로 다시 시도해 보세요.
5	404	`NOT_FOUND`	캠페인 또는 광고 그룹과 같은 일부 요청한 항목을 찾을 수 없습니다.	클라이언트 오류: 액세스하려는 리소스의 존재 여부와 ID를 확인하세요. 수정 없이 다시 시도하지 마세요.
6	409	`ALREADY_EXISTS`	클라이언트가 만들려고 시도한 항목이 이미 존재합니다.	클라이언트 오류: 중복 리소스 생성을 방지하세요. 리소스를 만들기 전에 리소스가 있는지 확인합니다.
7	403	`PERMISSION_DENIED`	호출자에 지정한 작업을 실행할 권한이 없습니다.	클라이언트 오류: Google Ads 계정의 인증, 승인, 사용자 역할을 확인하세요. 권한을 해결하지 않은 상태로 다시 시도하지 마세요.
8	429	`RESOURCE_EXHAUSTED`	리소스가 소진되었거나 (예: 할당량 초과) 시스템에 과부하가 걸렸습니다.	클라이언트/서버 오류: 일반적으로 기다려야 합니다. 지수 백오프를 구현하여 요청 비율을 줄일 수 있습니다. API 한도 및 할당량을 참고하세요.
9	400	`FAILED_PRECONDITION`	시스템이 작업 실행에 필요한 상태가 아니기 때문에 작업이 거부되었습니다. 예를 들어 필수 입력란이 누락되었습니다.	클라이언트 오류: 요청은 유효하지만 상태가 잘못되었습니다. 오류 세부정보를 검토하여 전제 조건 실패를 파악합니다. 상태를 수정하지 않고 다시 시도하지 마세요.
10	409	`ABORTED`	작업이 취소되었습니다. 대개 트랜잭션 충돌과 같은 동시 실행 문제가 원인입니다.	서버 오류: 짧은 백오프로 다시 시도해도 되는 경우가 많습니다.
11	400	`OUT_OF_RANGE`	유효한 범위를 벗어나는 작업을 시도했습니다.	클라이언트 오류: 범위 또는 색인을 수정합니다.
12	501	`UNIMPLEMENTED`	작업이 API에 의해 구현되지 않았거나 지원되지 않습니다.	클라이언트 오류: API 버전 및 사용 가능한 기능을 확인합니다. 재시도하지 마세요.
13	500	`INTERNAL`	내부 오류가 발생했습니다. 서버 측 문제의 일반적인 기타입니다.	서버 오류: 일반적으로 지수 백오프로 다시 시도할 수 있습니다. 문제가 계속되면 문제를 신고하세요.
14	503	`UNAVAILABLE`	현재 서비스를 사용할 수 없습니다. 일시적인 상태일 가능성이 높습니다.	서버 오류: 지수 백오프로 다시 시도하는 것이 좋습니다.
15	500	`DATA_LOSS`	복구할 수 없는 데이터 손실이나 손상이 발생했습니다.	서버 오류: 드물게 발생합니다. 심각한 문제를 나타냅니다. 재시도하지 마세요. 문제가 계속되면 문제를 신고하세요.
16	401	`UNAUTHENTICATED`	요청에 유효한 사용자 인증 정보가 없습니다.	클라이언트 오류: 인증 토큰과 사용자 인증 정보를 확인하세요. 인증을 수정하지 않고 다시 시도하지 마세요.

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

오류 세부정보 이해하기

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

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

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

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

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

오류 세부정보의 예

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

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.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를 사용하는 경우 HTTP 응답에 GoogleAdsFailure이 반환됩니다. 클라이언트 라이브러리는 일반적으로 GoogleAdsFailure 속성이 있는 예외로 이를 표시합니다.

부분 실패

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

일괄 작업

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

요청 ID

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

request-id는 여러 위치에서 찾을 수 있습니다.

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

오류를 기록하거나 지원팀에 문의할 때는 문제 진단에 도움이 되도록 request-id를 포함하세요.

오류 처리 권장사항

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

오류 세부정보 검사: 항상 Status 객체의 details 필드를 파싱하여 GoogleAdsFailure를 찾습니다. GoogleAdsError 내의 상세한 errorCode, message, location는 디버깅 및 사용자 의견에 가장 실용적인 정보를 제공합니다.
클라이언트 오류와 서버 오류 구분:
- 클라이언트 오류: INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED과 같은 코드 이러한 오류에는 요청 또는 애플리케이션의 상태/사용자 인증 정보를 변경해야 합니다. 문제를 해결하지 않고 요청을 다시 시도하지 마세요.
- 서버 오류: UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN과 같은 코드입니다. 이는 API 서비스에 일시적인 문제가 있음을 나타냅니다.
재시도 전략을 구현합니다.
- 재시도 시점: UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, ABORTED과 같은 일시적인 서버 오류에 대해서만 재시도하세요.
- 지수 백오프: 지수 백오프 알고리즘을 사용하여 재시도 간 대기 시간을 늘립니다. 이렇게 하면 이미 스트레스를 받고 있는 서비스에 과부하가 걸리지 않습니다. 예를 들어 1초, 2초, 4초 순으로 대기 시간을 늘려 최대 재시도 횟수 또는 총 대기 시간에 도달할 때까지 계속합니다.
- 지터: 많은 클라이언트가 동시에 재시도하는 'thundering herd' 문제를 방지하기 위해 백오프 지연에 작은 임의의 '지터'를 추가합니다.
철저하게 로깅: 모든 세부정보, 특히 요청 ID를 포함한 전체 오류 응답을 로깅합니다. 이 정보는 디버깅에 필수적이며 필요한 경우 Google 지원팀에 문제를 보고하는 데도 필요합니다.
사용자 의견 제공: 특정 GoogleAdsError 코드와 메시지에 따라 애플리케이션 사용자에게 명확하고 유용한 의견을 제공합니다. 예를 들어 '오류가 발생했습니다'라고만 말하는 대신 '캠페인 이름이 필요합니다' 또는 '제공된 광고 그룹 ID를 찾을 수 없습니다'라고 말할 수 있습니다.

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

API 오류 이해 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.