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

일반적인 오류

이 가이드에서는 일반적인 API 오류를 나열하고 이를 방지하고 처리하는 전략을 제공합니다.

모든 오류 유형의 전체 목록은 Google Ads API 오류 참조를 참고하세요. 추가 지원이 필요한 경우 Google Ads API 포럼에 질문을 게시하세요.

`google.rpc.ErrorInfo`

ACCESS_TOKEN_SCOPE_INSUFFICIENT

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

invalid_grant

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

CLIENT_CUSTOMER_ID_INVALID

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 헤더와 함께 전달된 액세스 토큰이 올바르지 않습니다.
대응 방법	해당 사항 없음
예방법	계정과 연결된 올바른 액세스 토큰을 전달했는지 확인합니다. 액세스 토큰은 갱신 토큰 및 승인 코드와 혼동되는 경우가 있습니다. 관리자 계정의 모든 고객 계정에 액세스할 수 있는 사용자 인증 정보를 얻으려면 관리자 계정의 갱신 토큰을 가져와야 합니다. 사용자 인증 가이드를 참고하세요.

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로 지정합니다. 클라이언트 라이브러리에는 이에 대한 지원이 내장되어 있습니다.