일반적인 오류

이 페이지에는 일반적인 오류가 나열되어 있으며 오류를 방지하고 처리하는 방법에 관한 팁이 제공됩니다. 전체 오류 목록은 오류 참조, API 오류 이해 가이드 또는 오류 유형 가이드를 참고하세요. 추가 지원이 필요하면 Google Ads API 지원팀에 문의하세요.

google.rpc.ErrorInfo
ACCESS_TOKEN_SCOPE_INSUFFICIENT	요약 OAuth 2.0 액세스 토큰에 필요한 범위가 없습니다. 일반적인 원인 제공된 액세스 토큰에 Google Ads API OAuth 2.0 범위가 포함되어 있지 않아 요청이 거부됩니다. 대응 방법 액세스 토큰에 필요한 범위가 있는지 확인합니다. 이 오류가 발생하는 일반적인 이유는 다른 OAuth 범위 집합을 사용하여 생성된 기존 액세스 토큰을 재사용하고 있기 때문입니다. 필요한 범위로 새 액세스 토큰을 생성하는 방법의 예는 OAuth 승인 매개변수를 참고하세요. 예방법 액세스 토큰에 필요한 범위가 있는지 확인합니다. 필요한 범위로 사용자를 재인증하여 필요한 범위로 액세스 권한을 획득합니다. 애플리케이션에서 여러 OAuth 범위를 사용하는 경우 세분화된 OAuth 권한을 구현해야 할 수 있습니다.

google.auth.exceptions.RefreshError
invalid_grant	요약 토큰이 만료되었거나 취소되었습니다. 일반적인 원인 외부 사용자 유형으로 구성되고 게시 상태가 Testing인 OAuth 동의 화면이 있는 Google Cloud Platform 프로젝트에는 7일 후에 만료되는 갱신 토큰이 발급됩니다. 대응 방법 Google 프로젝트의 게시 상태가 Testing이므로 갱신 토큰이 7일마다 만료되고 invalid_grant 오류가 발생합니다. Google API 콘솔로 이동하여 OAuth 동의 화면으로 이동합니다. 그런 다음 7일 후에 갱신 토큰이 만료되지 않도록 게시 상태를 In production로 변경합니다. 예방법 인증되지 않은 앱을 참고하세요.

AdError
CANNOT_USE_AD_SUBCLASS_FOR_OPERATOR	요약 이 연산자는 광고의 하위 클래스와 함께 사용할 수 없습니다. 일반적인 원인 광고의 status 이외의 속성을 수정하려고 합니다. 대응 방법 해당 사항 없음 예방법 광고가 생성되면 수정할 수 없습니다. 광고를 수정하려면 새 광고를 만든 후 이전 광고를 삭제해야 합니다. 하지만 광고의 status는 MutateAdGroupAds를 사용하여 수정할 수 있습니다.
INVALID_INPUT	요약 광고의 입력란 중 하나에 잘못된 문자가 포함되어 있습니다. 일반적인 원인 URL에 특수문자 사용 대응 방법 해당 사항 없음 예방법 API 요청을 하기 전에 앱에서 URL을 검증합니다.
LINE_TOO_WIDE	요약 광고의 필드 중 하나가 허용되는 최대 길이를 초과했습니다. 텍스트 광고에 대한 정보를 참고하세요. 일반적인 원인 텍스트 줄이 너무 깁니다. 대응 방법 해당 사항 없음 예방법 API 요청을 하기 전에 선의 길이를 검증합니다.

AdGroupAdError
AD_GROUP_AD_LABEL_ALREADY_EXISTS	요약 일부 광고에서 이미 이 라벨을 사용하고 있습니다. 일반적인 원인 이미 연결된 광고에 라벨을 연결하려고 합니다. 대응 방법 해당 사항 없음 예방법 먼저 추가할 라벨이 광고와 이미 연결되어 있는지 확인합니다.
CANNOT_OPERATE_ON_REMOVED_ADGROUPAD	요약 삭제된 광고를 업데이트하려고 시도한 작업입니다. 일반적인 원인 광고가 삭제되면 상태 변경을 비롯한 업데이트를 더 이상 할 수 없습니다. 대응 방법 해당 사항 없음 예방법 코드가 삭제된 광고를 업데이트하려고 시도하지 않는지 확인하세요.

AdGroupCriterionError
INVALID_KEYWORD_TEXT	요약 키워드에 잘못된 문자가 포함되어 있습니다. 키워드 추가를 참고하세요. 일반적인 원인 키워드에 잘못된 문자가 포함되어 있습니다. 대응 방법 해당 사항 없음 예방법 API에 요청하기 전에 앱의 키워드 텍스트를 검증합니다.

AdGroupError
DUPLICATE_ADGROUP_NAME	요약 광고 그룹이 추가되거나 이름이 변경되지만 이름이 이미 다른 광고 그룹에서 사용되고 있습니다. 일반적인 원인 운영 중이거나 일시중지된 기존 광고 그룹의 이름으로 새 광고 그룹을 만드는 경우 대응 방법 오류를 기록하고 사용자에게 오류 메시지를 표시합니다. 선택적으로 고유한 광고 그룹 이름을 제안하거나 사용 중인 이름 목록을 표시할 수 있습니다. 예방법 해당 사항 없음

AssetError
DUPLICATE_ASSET	요약 단일 요청의 두 작업에 동일한 바이너리 데이터가 있는 애셋의 생성 작업이 포함되어 있습니다. 일반적인 원인 동일한 바이너리 데이터가 포함된 중복된 생성 작업이 있는 mutate 요청입니다. 대응 방법 별도의 요청에서 애셋을 만든 다음 후속 요청에서 애셋에 연결하거나 동일한 요청 내에서 임시 ID를 사용합니다. 예방법 해당 사항 없음

AuthenticationError
CLIENT_CUSTOMER_ID_INVALID	요약 클라이언트 고객 ID가 숫자가 아닙니다. 일반적인 원인 부적절한 클라이언트 고객 ID를 사용합니다. 대응 방법 해당 사항 없음 예방법 123-456-7890은 1234567890이어야 합니다. 자세한 내용은 시작하기를 참고하세요.
CLIENT_CUSTOMER_ID_IS_REQUIRED	요약 클라이언트 고객 ID가 HTTP 헤더에 지정되지 않았습니다. 일반적인 원인 HTTP 헤더에 클라이언트 고객 ID를 지정하지 않습니다. 대응 방법 해당 사항 없음 예방법 클라이언트 고객 ID는 모든 호출에 필요하므로 HTTP 헤더에 지정했는지 확인하세요. 이 작업을 처리해 주는 클라이언트 라이브러리를 사용하는 것이 좋습니다.
CUSTOMER_NOT_FOUND	요약 헤더에 제공된 고객 ID의 계정을 찾을 수 없습니다. 일반적인 원인 계정이 백엔드에 설정되기 전에 방금 생성된 계정에 액세스하려고 합니다. 대응 방법 처음 5분 동안 기다린 후 30초마다 다시 시도합니다. 예방법 계정을 만든 후 몇 분 정도 기다렸다가 계정에 대해 요청을 실행하세요.
GOOGLE_ACCOUNT_COOKIE_INVALID	요약 요청 헤더의 액세스 토큰이 잘못되었거나 만료되었습니다. 일반적인 원인 액세스 토큰이 무효화되었습니다. 대응 방법 새 토큰을 요청합니다. Google 클라이언트 라이브러리 중 하나를 사용하는 경우 토큰을 새로고침하는 방법을 문서에서 확인하세요. 예방법 액세스 토큰이 만료될 때까지 저장하고 재사용합니다.
NOT_ADS_USER	요약 액세스 토큰을 생성하는 데 사용된 Google 계정이 Google Ads 계정과 연결되어 있지 않습니다. 일반적인 원인 제공된 로그인 정보가 Google Ads가 사용 설정되지 않은 Google 계정에 해당합니다. 대응 방법 OAuth 흐름을 위해 유효한 Google Ads 계정 (일반적으로 관리자 계정)으로 로그인해야 합니다. 관리자 계정에 로그인하고, 문제가 되는 고객 또는 관리자 계정을 선택하고, Tools and Settings > Access and security로 이동한 다음, Google 계정 이메일 주소를 추가하여 기존 Google Ads 계정에 액세스하도록 Google 계정을 초대할 수도 있습니다. 예방법 해당 사항 없음
OAUTH_TOKEN_INVALID	요약 헤더의 OAuth 액세스 토큰이 잘못되었습니다. 일반적인 원인 HTTP 헤더와 함께 전달된 액세스 토큰이 올바르지 않습니다. 대응 방법 해당 사항 없음 예방법 계정과 연결된 올바른 액세스 토큰을 전달했는지 확인합니다. 액세스 토큰은 갱신 토큰 및 승인 코드와 혼동되는 경우가 있습니다. 관리자 계정의 모든 고객 계정에 액세스할 수 있는 사용자 인증 정보를 얻으려면 관리자 계정의 갱신 토큰을 가져와야 합니다. 사용자 인증 가이드를 참고하세요.

AuthorizationError
CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION	요약 Google Cloud 프로젝트에는 테스트 액세스 권한만 있으며 프로덕션 계정에 액세스하는 데 사용할 수 없습니다. 일반적인 원인 테스트 액세스 수준이 있는 Google Cloud 프로젝트가 테스트가 아닌 (프로덕션) Google Ads 계정에 대해 요청을 만드는 데 사용되었습니다. (API 버전 v24 이하에서는 이 조건이 AuthorizationError.ACTION_NOT_PERMITTED를 반환합니다.) 대응 방법 테스트 중인 경우 요청이 테스트 계정을 타겟팅하는지 확인합니다. 프로덕션 Google Ads 계정에 액세스하려면 Google Ads API 개요 페이지에서 Google Cloud 프로젝트의 액세스 수준을 확인하고 프로젝트의 액세스 수준을 업그레이드하여 탐색기, 기본 또는 표준 액세스 권한을 부여하세요. 예방법 해당 사항 없음
CUSTOMER_NOT_ENABLED	요약 고객 계정이 사용 설정 상태가 아니므로 액세스할 수 없습니다. 일반적인 원인 고객 계정의 가입이 완료되지 않았거나 계정이 비활성화된 경우에 발생합니다. 대응 방법 Google Ads UI에 로그인하여 이 계정의 가입 절차를 완료했는지 확인합니다. 비활성화된 계정의 경우 해지된 Google Ads 계정 재활성화를 참고하세요. 예방법 CANCELLED 상태를 확인하여 고객 계정이 비활성화되었는지 사전에 확인할 수 있습니다.
USER_PERMISSION_DENIED	요약 승인된 고객이 운영 고객에 액세스할 수 없습니다. 일반적인 원인 관리자 계정에 대한 액세스 권한이 있는 사용자로 인증하지만 요청에 login-customer-id를 지정하지 않습니다. 대응 방법 해당 사항 없음 예방법 login-customer-id를 하이픈 (-)이 없는 관리자 계정 ID로 지정합니다. 클라이언트 라이브러리에는 이에 대한 지원이 내장되어 있습니다.

BiddingError
BID_TOO_MANY_FRACTIONAL_DIGITS	요약 입찰가가 계정 통화의 최소 단위의 정확한 배수가 아닙니다. 예를 들어 미화 0.015달러 (마이크로 단위로 15000)는 유효한 입찰가가 아닙니다. 일반적인 원인 해당 사항 없음 대응 방법 해당 사항 없음 예방법 입찰가가 계정 통화의 최소 단위의 배수인지 확인합니다.
BID_TOO_BIG	요약 입찰가가 캠페인 예산 내에 있어도 오류가 반환됩니다. 일반적인 원인 해당 사항 없음 대응 방법 해당 사항 없음 예방법 계정이 Google Ad Grants에 참여하고 있는지 확인합니다. 이 경우 CPC 입찰가를 프로그램에서 규정한 최대치로 제한하세요.

CampaignBudgetError
MONEY_AMOUNT_LESS_THAN_CURRENCY_MINIMUM_CPC	요약 예산 금액이 너무 적습니다. 일반적인 원인 해당 사항 없음 대응 방법 해당 사항 없음 예방법 예산 금액이 계정 통화의 최소 단위 이상인지 확인합니다.
NON_MULTIPLE_OF_MINIMUM_CURRENCY_UNIT	요약 마이크로 금액을 계정 통화의 금액으로 변환하면 예산 금액에 유효한 소수점 자릿수가 너무 많아집니다. 일반적인 원인 해당 사항 없음 대응 방법 해당 사항 없음 예방법 예산 금액이 계정 통화의 최소 단위로 나누어지는지 확인합니다.

CampaignError
DUPLICATE_CAMPAIGN_NAME	요약 캠페인이 추가되거나 이름이 변경되지만 이름이 이미 다른 캠페인에서 사용 중입니다. 일반적인 원인 활성 상태이거나 일시중지된 기존 캠페인의 이름으로 새 캠페인을 만드는 경우 대응 방법 오류를 기록하고 사용자에게 오류 메시지를 표시합니다. 선택적으로 고유한 캠페인 이름을 제안하거나 사용 중인 이름 목록을 표시할 수 있습니다. 예방법 해당 사항 없음
CANNOT_SET_CAMPAIGN_KEYWORD_MATCH_TYPE	요약 AI Max가 사용 설정된 캠페인에서 캠페인 수준 키워드 검색 유형 설정을 변경하려고 시도합니다. 일반적인 원인 AI Max가 사용 설정되면 모든 키워드가 기본적으로 확장검색으로 취급되므로 캠페인 수준 확장검색 설정이 지원 중단됩니다. 이 필드를 설정하거나 수정하려고 하면 오류가 발생합니다. 대응 방법 캠페인 수준에서 확장검색을 설정하는 대신 광고 그룹 수준에서 `disable_search_term_matching` 매개변수를 사용하도록 사용자에게 안내합니다. 예방법 `ai_max_setting.enable_ai_max` 가 `true`로 설정된 경우 캠페인에서 `keyword_match_type` 을 `BROAD` (또는 다른 값)로 설정하지 마세요. `disable_search_term_matching`을 사용하여 광고 그룹 수준에서 검색어 일치를 전환하세요.

CriterionError
KEYWORD_HAS_INVALID_CHARS	요약 잘못된 문자가 포함된 키워드를 추가하거나 수정하는 경우 일반적인 원인 키워드에 ! @ % *과 같은 특수문자를 사용합니다. 대응 방법 해당 사항 없음 예방법 키워드에 허용되지 않는 문자를 사용하지 않아야 합니다. 키워드 추가를 참고하세요.

DistinctError
DUPLICATE_ELEMENT	요약 요청에 동일하고 중복된 매개변수가 두 개 포함되어 있습니다. 일반적인 원인 해당 사항 없음 대응 방법 해당 사항 없음 예방법 요청하기 전에 중복 항목 (작업, 매개변수, 목록 요소)을 삭제하세요. DistinctElements 제약 조건이 있는 필드를 찾습니다.

InternalError
DEADLINE_EXCEEDED	요약 요청 시간이 초과되어 응답을 반환할 만큼 빠르게 완료할 수 없습니다. 일반적인 원인 검색 요청으로 인해 응답이 너무 커졌거나 mutate 요청이 너무 커서 처리할 수 없습니다. 대응 방법 30초 후에 요청을 다시 시도하세요. 오류가 계속되면 요청을 더 빨리 완료할 수 있는 여러 개의 작은 요청으로 나누어 보세요. 예방법 세분화를 검토하여 응답 크기에 미치는 영향을 파악하세요. gRPC 전송 계층 제한사항에 유의하세요.
INTERNAL_ERROR	요약 요청을 처리하는 중에 예상치 못한 문제가 발생했습니다. 일반적인 원인 버그로 인해 API가 제대로 작동하지 않습니다. 대응 방법 이 오류로 인해 실패한 요청을 재시도할 때는 재시도에 지수 백오프 일정을 사용하세요. 예방법 해당 사항 없음
TRANSIENT_ERROR	요약 일시적인 내부 오류가 발생했으며 다시 시도해야 합니다. 일반적인 원인 이 오류는 API에서 내부적으로 일시적인 문제가 발생할 때 발생합니다. 대응 방법 이 오류로 인해 실패한 요청을 재시도할 때는 재시도에 지수 백오프 일정을 사용하세요. 예방법 해당 사항 없음

InvalidGrantError
invalid_grant (malformed auth code)	요약 OAuth 토큰으로 교환된 승인 코드가 형식이 잘못되었습니다. 일반적인 원인 이는 요청 애플리케이션에 이미 액세스 권한이 부여된 사용자의 갱신 토큰을 생성하려고 할 때 발생합니다. 예를 들어 동일한 OAuth 클라이언트 사용자 인증 정보 및 승인된 사용자에 대해 사용자 사용자 인증 정보 생성 예시를 두 번 이상 실행할 때 이러한 상황이 발생할 수 있습니다. 대응 방법 승인 사용자 및 OAuth 클라이언트 사용자 인증 정보의 지정된 조합에 대한 갱신 토큰을 재생성하려면 기존 갱신 토큰을 취소하세요. 토큰을 취소하면 Google Ads API 액세스에 사용할 수 없게 되며 갱신 토큰을 사용하여 생성된 액세스 토큰이 무효화됩니다. 예방법 재생성할 필요가 없도록 갱신 토큰을 안전한 위치에 저장해야 합니다.

MutateError
RESOURCE_NOT_FOUND	요약 요청에서 찾을 수 없는 리소스를 참조했습니다. 일반적인 원인 요청에서 존재하지 않거나 삭제된 리소스를 변경하거나 참조하려고 했습니다. 또는 리소스의 지정된 리소스 이름이 잘못되었습니다. 대응 방법 변이 요청을 제출하기 전에 검색 요청을 사용하여 기존 리소스의 리소스 이름을 가져옵니다. 지원되는 모든 언어로 유효한 리소스 이름을 구성하는 방법에 관한 문서가 포함된 클라이언트 라이브러리 가이드를 검토하세요. 예방법 리소스 이름을 수동으로 만들지 마세요. Google 클라이언트 라이브러리에서 제공하는 도우미 메서드 중 하나를 사용합니다.

NotEmptyError
EMPTY_LIST	요약 필수 목록이 비어 있습니다. 일반적인 원인 mutate 메서드에 빈 작업 목록을 전달합니다. 대응 방법 해당 사항 없음 예방법 해당 사항 없음

QuotaError
RESOURCE_EXHAUSTED	요약 시스템 빈도 제한을 초과했습니다. 일반적인 원인 해당 사항 없음 대응 방법 해당 사항 없음 예방법 요청 간에 짧은 지연 시간을 설정하거나 더 적은 요청에 더 많은 작업을 결합합니다.

RangeError
TOO_LOW	요약 값이 허용되는 최솟값보다 낮습니다. 일반적인 원인 ID를 지정하지 않아 0 값이 전달됩니다. 대응 방법 해당 사항 없음 예방법 API 참조에 설명된 범위 제한사항을 참고하세요.

RequestError
INVALID_INPUT	요약 요청의 형식이 잘못되었습니다. 일반적인 원인 요청의 URL 또는 콘텐츠가 잘못된 형식입니다. 대응 방법 해당 사항 없음 예방법 해당 사항 없음
REQUIRED_FIELD_MISSING	요약 요청에 필수 정보가 누락되었습니다. 일반적인 원인 항목을 추가하려고 할 때 필수 입력란이 누락되었습니다. 대응 방법 오류를 기록하고 사용자에게 오류 메시지를 표시합니다. 오류의 fieldPath 속성은 누락된 필드를 나타냅니다. 예방법 API 참조를 참고하여 필수 필드를 확인하세요.

ResourceCountLimitExceededError
RESOURCE_LIMIT	요약 요청에서 해당 리소스의 총수가 지정된 한도를 초과하는 리소스를 만들려고 시도합니다. 일반적인 원인 특정 컨텍스트에 존재할 수 있는 리소스 수에는 여러 제한이 있습니다. 대응 방법 시스템 한도를 검토하여 발생한 한도를 식별합니다. 기존 리소스를 재사용하거나 리소스를 삭제하여 새 리소스를 위한 공간을 만듭니다. 예방법 검색어를 사용하여 제한이 있는 리소스 수를 모니터링합니다.

StringLengthError
TOO_LONG	요약 지정된 필드에 할당된 문자열이 한도를 초과합니다. 일반적인 원인 광고의 광고 제목 또는 내용 입력란에 텍스트가 너무 많이 포함되어 있습니다. 대응 방법 발생한 한도를 확인하고 문자열을 적절하게 수정하고 요청을 다시 보냅니다. 예방법 문자열 길이 제한에 유의하세요.