Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

API 오류 이해

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

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

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

표준 오류 코드

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

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

gRPC 코드	HTTP 코드	enum 이름	설명	가이드
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`	리소스가 소진되었거나 (예: 할당량 초과) 시스템에 과부하가 발생했습니다.	클라이언트/서버 오류: 일반적으로 기다려야 합니다. 지수 백오프를 구현하고 요청 비율을 줄입니다. I am going to provide a list of glossary for this session. Use these terms as references, but apply your own judgment based on the definitions provided. If a term doesn't fit the context, just ignore the suggestion.Source Term: API limitThe definition is: The maximum number of API requests allowed within a given timeframe to protect system performance.Translation under this definition: 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 객체는 다음을 제공합니다.

error_code: 보다 세분화된 Google Ads API 관련 ErrorCode(일반적인 오류)(예: AuthenticationError.NOT_ADS_USER)
message: 특정 오류에 대해 인간이 읽을 수 있는 설명입니다.
trigger: 오류를 일으킨 Value입니다(해당하는 경우).
location: 필드 경로를 포함하여 요청에서 오류가 발생한 위치를 설명하는 ErrorLocation입니다.
details: 게시되지 않은 오류 이유와 같은 추가 ErrorDetails입니다.

오류 세부정보의 예

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

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

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

오류 세부정보 찾기

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

표준 및 스트리밍 API 호출

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

부분 실패

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

일괄 작업

일괄 처리의 경우 작업이 완료된 후 BatchJobService.ListBatchJobResults를 호출하여 개별 작업의 오류를 찾을 수 있습니다. 각 작업 결과에는 작업이 실패한 경우 오류 세부정보가 포함된 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를 포함해야 합니다.

오류 처리 권장사항

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

오류 세부정보 검사: 항상 Status 객체의 details 필드를 파싱하여 특히 GoogleAdsFailure를 찾습니다. GoogleAdsError 내의 세분화된 error_code, 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 오류 이해 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.