일반적인 오류
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 페이지에는 일반적인 오류가 나열되어 있으며 오류를 방지하고 처리하는 방법에 관한 팁이 제공됩니다.
전체 오류 목록은 오류 참조를 참고하세요. 추가 지원이 필요하면 포럼을 방문하세요.
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 동의 화면으로 이동합니다. 그런 다음 이 안내에 따라 게시 상태를 In production로 변경하여 7일 후에 갱신 토큰이 만료되지 않도록 하세요.
|
|---|
| 예방법 |
인증되지 않은 앱을 참고하세요.
|
|---|
|
|
CLIENT_CUSTOMER_ID_INVALID |
| 요약 | 클라이언트 고객 ID가 숫자가 아닙니다. |
|---|
| 일반적인 원인 |
부적절한 클라이언트 고객 ID를 사용하고 있습니다.
|
|---|
| 처리 방법 |
해당 사항 없음
|
|---|
| 예방법 |
123-456-7890은 1234567890이어야 합니다. 자세한 내용은 시작하기를 참고하세요.
|
|---|
|
CLIENT_CUSTOMER_ID_IS_REQUIRED |
| 요약 | HTTP 헤더에 클라이언트 고객 ID가 지정되지 않았습니다. |
|---|
| 일반적인 원인 |
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 헤더와 함께 전달된 액세스 토큰이 올바르지 않습니다.
|
|---|
| 처리 방법 |
해당 사항 없음
|
|---|
| 예방법 |
계정과 연결된 올바른 액세스 토큰을 전달했는지 확인합니다. 액세스 토큰은 갱신 토큰 및 승인 코드와 혼동되는 경우가 있습니다. 관리자 계정의 모든 고객 계정에 액세스할 수 있는 사용자 인증 정보를 얻으려면 관리자 계정의 새로고침 토큰을 가져와야 합니다. 자세한 내용은 액세스 토큰 및 갱신 토큰 및 OAuth2에 관한 가이드를 참고하세요.
|
|---|
|
ORGANIZATION_NOT_ASSOCIATED_WITH_DEVELOPER_TOKEN |
| 요약 | 개발자 토큰이 이미 Google Cloud 조직과 연결되어 있으므로 다른 조직과 연결할 수 없습니다. |
|---|
| 일반적인 원인 |
개발자 토큰이 원래 요청을 만드는 데 사용된 Google Cloud 프로젝트와 동일한 Google Cloud 조직의 Google Cloud 프로젝트와 연결되어 있지 않습니다.
|
|---|
| 처리 방법 |
개발자 토큰으로 API 요청을 이미 한 경우 OAuth 클라이언트 ID가 동일한 Google Cloud 조직의 Google Cloud 프로젝트와 연결되어 있는지 확인합니다.
|
|---|
| 예방법 |
모든 Google Cloud 프로젝트가 동일한 Google Cloud 조직과 연결되어 있어야 합니다. Google Cloud 프로젝트는 하나의 개발자 토큰에만 연결할 수 있지만 개발자 토큰은 조직의 여러 프로젝트에 연결할 수 있습니다.
|
|---|
|
DEVELOPER_TOKEN_INVALID |
| 요약 | 개발자 토큰이 잘못되었습니다. |
|---|
| 일반적인 원인 |
이 오류의 일반적인 원인은 개발자 토큰의 오타 또는 다른 요청 헤더에서 개발자 토큰을 잘못 설정한 경우입니다.
|
|---|
| 처리 방법 |
오타를 방지하려면 API 센터에서 개발자 토큰을 복사해야 합니다. Google Ads 관리자 계정에서 API 센터를 찾을 수 있습니다. 또한 올바른 헤더에 개발자 토큰을 설정해야 합니다. 개발자 토큰은 OAuth 갱신 토큰 및 승인 코드와 혼동되는 경우가 있습니다. 다양한 요청 헤더에 대해 자세히 알아보려면 여기를 참고하세요.
|
|---|
| 예방법 |
해당 사항 없음
|
|---|
|
|
CUSTOMER_NOT_ENABLED |
| 요약 | 고객 계정이 사용 설정 상태가 아니므로 액세스할 수 없습니다. |
|---|
| 일반적인 원인 |
이는 고객 계정의 가입이 완료되지 않았거나 비활성화된 경우에 발생합니다.
|
|---|
| 처리 방법 |
Google Ads UI에 로그인하여 이 계정의 가입 절차를 완료했는지 확인합니다. 비활성화된 계정의 경우 해지된 Google Ads 계정 재활성화를 참고하세요.
|
|---|
| 예방법 |
CANCELLED 상태를 확인하여 고객 계정이 비활성화되었는지 사전에 확인할 수 있습니다.
|
|---|
|
DEVELOPER_TOKEN_NOT_APPROVED |
| 요약 | 개발자 토큰이 테스트 계정에서만 사용하도록 승인되었는데 테스트 계정이 아닌 계정에 액세스하려고 시도했습니다. |
|---|
| 일반적인 원인 |
테스트 개발자 토큰을 사용하여 테스트 계정이 아닌 계정에 액세스했습니다.
|
|---|
| 처리 방법 |
테스트 계정이 아닌 계정에 액세스하려고 하는지 확인합니다. 이 경우 개발자 토큰을 스탠더드 또는 기본 액세스로 업그레이드 신청해야 합니다.
|
|---|
| 예방법 |
해당 사항 없음
|
|---|
|
DEVELOPER_TOKEN_PROHIBITED |
| 요약 | 개발자 토큰은 요청에 전송된 프로젝트와 함께 사용할 수 없습니다. |
|---|
| 일반적인 원인 |
각 Google API 콘솔 프로젝트는 하나의 관리자 계정의 개발자 토큰과만 연결할 수 있습니다. Google Ads API 요청을 하면 개발자 토큰이 Google API 콘솔 프로젝트와 영구적으로 페어링됩니다. 새 Google API 콘솔 프로젝트를 사용하지 않으면 요청 시 DEVELOPER_TOKEN_PROHIBITED 오류가 발생합니다.
|
|---|
| 처리 방법 |
해당 사항 없음
|
|---|
| 예방법 |
새 관리자 계정의 개발자 토큰으로 전환하는 경우 새 관리자의 토큰을 사용하는 Google Ads API 요청을 위해 새 Google API 콘솔 프로젝트를 만들어야 합니다.
|
|---|
|
USER_PERMISSION_DENIED |
| 요약 | 승인된 고객이 운영 고객에 액세스할 수 없습니다. |
|---|
| 일반적인 원인 |
관리자 계정에 액세스할 수 있는 사용자로 인증하지만 요청에 login-customer-id를 지정하지 않습니다.
|
|---|
| 처리 방법 |
해당 사항 없음
|
|---|
| 예방법 |
login-customer-id를 하이픈 없이 (-) 관리자 계정 ID로 지정합니다. 클라이언트 라이브러리에는 이에 대한 지원이 내장되어 있습니다.
|
|---|
|
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-31(UTC)
[null,null,["최종 업데이트: 2025-08-31(UTC)"],[[["\u003cp\u003eThis page provides solutions and preventative measures for common Google Ads API errors.\u003c/p\u003e\n"],["\u003cp\u003eFor a comprehensive list of errors, refer to the dedicated error references section.\u003c/p\u003e\n"],["\u003cp\u003eAdditional assistance and community support can be found on the Google Ads API forum.\u003c/p\u003e\n"],["\u003cp\u003eUnderstanding and addressing these errors is crucial for successful API integration and campaign management.\u003c/p\u003e\n"]]],[],null,[]]
