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

오류 유형

Google에서는 오류를 다음과 같은 광범위한 카테고리로 분류했습니다.

인증
재시도 가능한 오류
유효성 검사
동기화 관련

이러한 카테고리가 발생할 수 있는 모든 오류를 포함하지 않고 일부는 두 개 이상의 카테고리에 속할 수 있지만, 앱의 오류 처리 구조를 지정하는 시작점으로 사용할 수 있습니다. 특정 오류에 관한 자세한 내용은 다음 리소스를 참고하세요.

일반적인 오류에는 특정 오류에 대한 자세한 내용이 나와 있습니다.
google.rpc.Status은 API에서 사용하는 논리적 오류 모델에 관한 세부정보를 제공합니다.
표준 오류 코드에서는 Google Ads API 컨텍스트에서 gRPC 및 HTTP로 정의된 표준 오류 코드의 목록과 설명을 제공합니다.

인증 오류

인증은 사용자를 대신하여 Google Ads에 액세스할 수 있는 권한이 앱에 부여되었는지 여부를 나타냅니다. 인증은 OAuth2 흐름에서 생성된 사용자 인증 정보를 통해 관리됩니다.

인증 오류가 발생하는 가장 일반적인 이유는 인증된 사용자가 앱이 사용자를 대신하여 행동할 수 있도록 부여한 권한을 취소했기 때문입니다. 예를 들어 앱이 독립적인 고객의 별도 Google Ads 계정을 관리하고 고객의 계정을 관리할 때 각 고객으로 별도로 인증하는 경우 고객은 언제든지 앱의 액세스 권한을 취소할 수 있습니다. 액세스 권한이 취소된 시점에 따라 API가 AuthenticationError.OAUTH_TOKEN_REVOKED 오류를 직접 반환하거나 클라이언트 라이브러리의 내장 사용자 인증 정보 객체가 토큰 취소 예외를 발생시킬 수 있습니다. 어떤 경우든 앱에 클라이언트용 UI가 있는 경우 클라이언트에게 OAuth2 흐름을 다시 실행하여 클라이언트를 대신하여 행동할 수 있는 앱의 권한을 다시 설정하도록 요청할 수 있습니다.

이와 관련하여 Google Cloud 프로젝트에 테스트 액세스 수준만 있고 프로덕션(테스트 아님) 계정에 대해 요청을 시도하면 API에서 AuthorizationError를 반환하며, 이 열거형 값은 API 버전에 따라 달라집니다.

v25부터: 반품 AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION
v24 이하: AuthorizationError.ACTION_NOT_PERMITTED를 반환합니다.

재시도 가능한 오류

TRANSIENT_ERROR 또는 INTERNAL_ERROR과 같은 일부 오류는 잠시 멈춘 후 요청을 다시 시도하면 해결될 수 있는 일시적인 문제를 나타낼 수 있습니다.

사용자 시작 요청의 경우 한 가지 전략은 UI에 오류를 즉시 표시하고 사용자에게 재시도를 트리거하는 옵션을 제공하는 것입니다. 또는 앱에서 먼저 요청을 자동으로 재시도하고 최대 재시도 횟수 또는 총 사용자 대기 시간에 도달한 후에만 UI에 오류를 노출할 수 있습니다.

백엔드에서 시작된 요청의 경우 앱은 최대 재시도 횟수까지 요청을 자동으로 재시도해야 합니다.

요청을 다시 시도할 때는 무작위 지터를 사용하여 지수 백오프 정책을 사용하세요. 예를 들어 첫 번째 재시도 전에 5초 동안 일시중지한 경우 두 번째 재시도 후에는 10초, 세 번째 재시도 후에는 20초 동안 일시중지하고 각 간격에 작은 무작위 지연을 추가하여 동기화된 재시도 스파이크를 방지할 수 있습니다. 지수 백오프는 API를 너무 공격적으로 호출하지 않도록 하는 데 도움이 됩니다. 재시도를 모두 소진한 후에도 오류가 지속되면 문제 해결을 위해 응답에서 request-id를 로깅합니다.

확인 오류

유효성 검사 오류는 작업에 대한 입력이 허용되지 않았음을 나타냅니다. 예로는 PolicyViolationError, DateError, DateRangeError, StringLengthError, UrlFieldError이 있습니다.

유효성 검사 오류는 사용자가 잘못된 입력을 입력한 사용자 시작 요청에서 가장 흔하게 발생합니다. 이러한 경우 수신한 특정 API 오류에 따라 사용자에게 적절한 오류 메시지를 제공해야 합니다. API를 호출하기 전에 일반적인 실수에 대해 사용자 입력을 검증하여 앱의 응답성을 높이고 API 사용을 더 효율적으로 만들 수도 있습니다. 백엔드에서 요청하는 경우 앱은 사람이 검토할 수 있도록 실패한 작업을 대기열에 추가할 수 있습니다.

동기화 관련 오류

많은 Google Ads 앱이 Google Ads 객체를 저장하기 위해 로컬 데이터베이스를 유지합니다. 이 접근 방식의 한 가지 문제점은 로컬 데이터베이스가 Google Ads의 실제 객체와 동기화되지 않을 수 있다는 것입니다. 예를 들어 사용자가 Google Ads에서 직접 광고 그룹을 삭제할 수 있지만 앱과 로컬 데이터베이스는 변경사항을 알지 못하고 광고 그룹이 있는 것처럼 API 호출을 계속 실행합니다. 이러한 동기화 문제는 DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD 등 다양한 오류로 나타날 수 있습니다.

사용자 시작 요청의 경우 한 가지 전략은 사용자에게 동기화 문제가 발생할 수 있다고 알리고, 관련 Google Ads 객체 클래스를 가져와 로컬 데이터베이스를 업데이트하는 작업을 즉시 실행한 다음 사용자에게 UI를 새로고침하라는 메시지를 표시하는 것입니다.

백엔드 요청의 경우 일부 오류는 앱이 로컬 데이터베이스를 자동으로 점진적으로 수정할 수 있는 충분한 정보를 제공합니다. 예를 들어 CANNOT_OPERATE_ON_REMOVED_ADGROUPAD로 인해 앱이 로컬 데이터베이스에서 해당 광고를 삭제된 것으로 표시해야 합니다. 이러한 방식으로 처리할 수 없는 오류로 인해 앱이 더 완전한 동기화 작업을 시작하거나 인간 작업자가 검토할 대기열에 추가될 수 있습니다.

API 오류 이해