인증은 사용자를 대신하여 Google Ads에 액세스할 수 있는 권한이 앱에 부여되었는지 여부를 나타냅니다. 인증은 OAuth2 흐름에서 생성된 사용자 인증 정보를 통해 관리됩니다.
인증 오류가 발생하는 가장 일반적인 이유는 인증된 사용자가 앱이 자신을 대신하여 행동할 수 있도록 부여한 권한을 취소했기 때문입니다. 예를 들어 앱이 독립적인 고객의 별도 Google Ads 계정을 관리하고 고객의 계정을 관리할 때 각 고객으로 별도로 인증하는 경우 고객은 언제든지 앱의 액세스 권한을 취소할 수 있습니다. 액세스 권한이 취소된 시점에 따라 API에서 AuthenticationError.OAUTH_TOKEN_REVOKED 오류를 직접 반환하거나 클라이언트 라이브러리의 내장 사용자 인증 정보 객체에서 토큰 취소 예외를 발생시킬 수 있습니다. 어떤 경우든 앱에 클라이언트용 UI가 있는 경우 클라이언트에게 OAuth2 흐름을 다시 시작하여 클라이언트를 대신하여 작업할 수 있는 앱의 권한을 다시 설정하도록 요청할 수 있습니다.
사용자 시작 요청의 경우 한 가지 전략은 UI에 오류를 즉시 표시하고 사용자에게 재시도를 트리거하는 옵션을 제공하는 것입니다. 또는 앱에서 먼저 요청을 자동으로 재시도하고 최대 재시도 횟수 또는 총 사용자 대기 시간에 도달한 후에만 UI에 오류를 노출할 수 있습니다.
백엔드에서 시작된 요청의 경우 앱이 최대 재시도 횟수까지 요청을 자동으로 재시도해야 합니다.
요청을 다시 시도할 때는 지수 백오프 정책을 사용하세요. 예를 들어 첫 번째 재시도 전에 5초 동안 일시중지했다면 두 번째 재시도 후에는 10초, 세 번째 재시도 후에는 20초 동안 일시중지할 수 있습니다. 지수 백오프는 API를 너무 적극적으로 호출하지 않도록 하는 데 도움이 됩니다.
유효성 검사 오류는 사용자가 잘못된 입력을 입력한 사용자 시작 요청에서 가장 흔하게 발생합니다. 이 경우 수신한 특정 API 오류에 따라 사용자에게 적절한 오류 메시지를 제공해야 합니다. API를 호출하기 전에 일반적인 실수에 대해 사용자 입력을 검증하여 앱의 응답성을 높이고 API 사용을 더 효율적으로 만들 수도 있습니다. 백엔드에서 요청하는 경우 앱은 사람이 검토할 수 있도록 실패한 작업을 대기열에 추가할 수 있습니다.
사용자 시작 요청의 경우 한 가지 전략은 사용자에게 동기화 문제가 발생할 수 있음을 알리고, 관련 Google Ads 객체 클래스를 가져와 로컬 데이터베이스를 업데이트하는 작업을 즉시 실행한 다음 사용자에게 UI를 새로고침하라는 메시지를 표시하는 것입니다.
백엔드 요청의 경우 일부 오류는 앱이 로컬 데이터베이스를 자동으로 점진적으로 수정할 수 있는 충분한 정보를 제공합니다. 예를 들어 CANNOT_OPERATE_ON_REMOVED_ADGROUPAD를 사용하면 앱이 로컬 데이터베이스에서 해당 광고를 삭제된 것으로 표시해야 합니다. 이러한 방식으로 처리할 수 없는 오류가 발생하면 앱에서 더 완전한 동기화 작업을 시작하거나 인간 운영자가 검토할 대기열에 추가될 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[[["\u003cp\u003eGoogle Ads API errors are categorized into Authentication, Retryable, Validation, and Sync-related errors for easier handling.\u003c/p\u003e\n"],["\u003cp\u003eAuthentication errors often stem from revoked user permissions and can be resolved by re-initiating the OAuth2 flow.\u003c/p\u003e\n"],["\u003cp\u003eRetryable errors, like \u003ccode\u003eTRANSIENT_ERROR\u003c/code\u003e or \u003ccode\u003eINTERNAL_ERROR\u003c/code\u003e, can be addressed with exponential backoff retry strategies.\u003c/p\u003e\n"],["\u003cp\u003eValidation errors arise from unacceptable input and require providing specific error messages to users or queuing for review.\u003c/p\u003e\n"],["\u003cp\u003eSync-related errors indicate discrepancies between your local data and Google Ads, necessitating data refreshes or sync jobs.\u003c/p\u003e\n"]]],[],null,["# Error Types\n\nWe've categorized errors into the following broad categories:\n\n- Authentication\n- Retryable\n- Validation\n- Sync-related\n\nThough these categories don't encompass all possible errors, and\nsome may fit into more than one category, they can nevertheless serve as\na starting point for structuring your app's error handling. See the following\nresources for more details about specific errors:\n\n- [Common Errors](/google-ads/api/docs/common-errors) provides more details about a particular error.\n- [google.rpc.Status](/google-ads/api/reference/rpc/google.rpc#status) for details about the logical error model used by the API.\n\nAuthentication errors\n---------------------\n\nAuthentication refers to whether your app has been given permission by a user to\naccess Google Ads on their behalf. Authentication is managed through\ncredentials generated by the [OAuth2 flow](/google-ads/api/docs/oauth/overview).\n\nThe most common reason an authentication error arises from factors beyond your\ncontrol is that the authenticated user has revoked the permission they gave your\napp to act on their behalf. For example, if your app manages separate Google Ads\naccounts for independent clients and authenticates separately as each client\nwhen managing that client's account, a client could revoke your app's access at\nany time. Depending on when your access was revoked, the API may directly return\nan `AuthenticationError.OAUTH_TOKEN_REVOKED` error, or the built-in credential\nobjects in the [Client Libraries](/google-ads/api/docs/client-libs) may throw a\ntoken revoked exception. In either case, if your app has a UI for your clients,\nit could ask them to relaunch the OAuth2 flow to reestablish your app's\npermission to act on their behalf.\n\nRetryable errors\n----------------\n\nSome errors, such as [`TRANSIENT_ERROR`](/google-ads/api/reference/rpc/v21/InternalErrorEnum.InternalError#transient_error)\nor [`INTERNAL_ERROR`](/google-ads/api/reference/rpc/v21/InternalErrorEnum.InternalError#internal_error),\ncan indicate a temporary problem that may be resolved by retrying the\nrequest after a short pause.\n\nFor user-initiated requests, one strategy is to immediately indicate an error in\nyour UI and give the user an option to trigger a retry. Alternatively, your app\ncould first automatically retry the request, only exposing the error in the UI\nafter reaching a maximum number of retries or total user wait time.\n\nFor requests initiated on the back end, your app should automatically retry the\nrequest up to a maximum number of retries.\n\nWhen you retry requests, use an exponential backoff policy. For example, if you\nfirst pause 5 seconds before the first retry, you could pause 10 seconds after\nthe second and 20 seconds after the third retry. Exponential backoff helps\nensure you are not calling the API too aggressively.\n\nValidation errors\n-----------------\n\nValidation errors indicate that an input to an operation was not acceptable.\nFor example, [`PolicyViolationError`](/google-ads/api/reference/rpc/v21/PolicyViolationErrorEnum.PolicyViolationError),\n[`DateError`](/google-ads/api/reference/rpc/v21/DateErrorEnum.DateError),\n[`DateRangeError`](/google-ads/api/reference/rpc/v21/DateRangeErrorEnum.DateRangeError),\n[`StringLengthError`](/google-ads/api/reference/rpc/v21/StringLengthErrorEnum.StringLengthError), and\n[`UrlFieldError`](/google-ads/api/reference/rpc/v21/UrlFieldErrorEnum.UrlFieldError).\n\nValidation errors occur most commonly in user-initiated requests, where a user\nhas entered invalid input. In these cases, you should provide an appropriate\nerror message to the user based on the specific API error you received. You can\nalso validate user input for common mistakes before making an API call, making\nyour app more responsive and your API usage more efficient. For requests from\nthe back end, your app could add the failed operation to a queue\nfor a human operator to review.\n\nSync-related errors\n-------------------\n\nMany Google Ads apps maintain a local database to store their Google Ads objects. One\nchallenge to this approach is that the local database may go out of sync with\nthe actual objects in Google Ads. For example, a user might delete an ad group\ndirectly in Google Ads, but the app and local database are unaware of the change and\ncontinue to issue API calls as if the ad group existed. These sync issues can\nmanifest as a variety of errors such as [`DUPLICATE_CAMPAIGN_NAME`](/google-ads/api/reference/rpc/v21/CampaignErrorEnum.CampaignError#duplicate_campaign_name),\n[`DUPLICATE_ADGROUP_NAME`](/google-ads/api/reference/rpc/v21/AdGroupErrorEnum.AdGroupError#duplicate_adgroup_name),\n[`AD_NOT_UNDER_ADGROUP`](/google-ads/api/reference/rpc/v21/AdGroupAdErrorEnum.AdGroupAdError#ad_not_under_adgroup),\n[`CANNOT_OPERATE_ON_REMOVED_ADGROUPAD`](/google-ads/api/reference/rpc/v21/AdGroupAdErrorEnum.AdGroupAdError#cannot_operate_on_removed_adgroupad),\nand many others.\n\nFor user-initiated requests, one strategy is to alert the user to a possible\nsync problem, immediately launch a job that retrieves the relevant class of\nGoogle Ads objects and updates the local database, then prompt the user to refresh\nthe UI.\n\nFor back-end requests, some errors provide enough information for your\napp to automatically and incrementally correct your local database. For example,\n[`CANNOT_OPERATE_ON_REMOVED_ADGROUPAD`](/google-ads/api/reference/rpc/v21/AdGroupAdErrorEnum.AdGroupAdError#cannot_operate_on_removed_adgroupad)\nshould cause your app to mark that ad as\nremoved in your local database. Errors that you cannot handle in this way could\ncause your app to launch a more complete sync job or be added to a queue for a\nhuman operator to review."]]
