با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
ما خطاها را به دسته‌های کلی زیر دسته‌بندی کرده‌ایم:
احراز هویت
قابل امتحان مجدد
اعتبار سنجی
مرتبط با همگام سازی
اگرچه این دسته‌بندی‌ها همه خطاهای احتمالی را در بر نمی‌گیرند، و برخی ممکن است در بیش از یک دسته قرار گیرند، با این وجود می‌توانند به عنوان نقطه شروعی برای ساختاردهی مدیریت خطای برنامه شما باشند. برای جزئیات بیشتر در مورد خطاهای خاص به منابع زیر مراجعه کنید:
Common Errors جزئیات بیشتری در مورد یک خطای خاص ارائه می دهد.
google.rpc.Status برای جزئیات مربوط به مدل خطای منطقی مورد استفاده توسط API.
خطاهای احراز هویت
احراز هویت به این اشاره دارد که آیا کاربر به برنامه شما اجازه دسترسی به Google Ads از طرف او را داده است یا خیر. احراز هویت از طریق اعتبارنامه های تولید شده توسط جریان OAuth2 مدیریت می شود.
رایج‌ترین دلیلی که خطای احراز هویت از عواملی خارج از کنترل شما ایجاد می‌شود این است که کاربر احراز هویت شده مجوزی را که به برنامه شما برای اقدام از جانب خود داده است، لغو کرده است. برای مثال، اگر برنامه شما حساب‌های Google Ads جداگانه را برای مشتریان مستقل مدیریت کند و هنگام مدیریت حساب آن مشتری، به‌صورت جداگانه به‌عنوان هر مشتری احراز هویت می‌کند، مشتری می‌تواند در هر زمانی دسترسی برنامه شما را لغو کند. بسته به زمانی که دسترسی شما لغو شده است، API ممکن است مستقیماً یک خطای AuthenticationError.OAUTH_TOKEN_REVOKED برگرداند، یا اشیاء اعتبار داخلی در کتابخانه‌های سرویس گیرنده ممکن است یک استثنا لغو نشانه ایجاد کنند. در هر صورت، اگر برنامه شما یک رابط کاربری برای مشتریان شما دارد، می‌تواند از آنها بخواهد که جریان OAuth2 را مجدداً راه‌اندازی کنند تا مجوز برنامه شما برای اقدام از طرف آنها دوباره برقرار شود.
خطاهای قابل امتحان مجدد
برخی از خطاها، مانند TRANSIENT_ERROR یا INTERNAL_ERROR ، می تواند نشان دهنده یک مشکل موقتی باشد که ممکن است با تلاش مجدد درخواست پس از یک مکث کوتاه برطرف شود.
برای درخواست‌های آغاز شده توسط کاربر، یک استراتژی این است که فوراً یک خطا را در رابط کاربری خود نشان دهید و به کاربر گزینه‌ای برای شروع مجدد امتحان بدهید. از طرف دیگر، برنامه شما می‌تواند ابتدا به‌طور خودکار درخواست را مجدداً امتحان کند، تنها پس از رسیدن به حداکثر تعداد تلاش‌های مجدد یا کل زمان انتظار کاربر، خطا را در رابط کاربری فاش می‌کند.
برای درخواست‌هایی که در قسمت پشتی شروع می‌شوند، برنامه شما باید به‌طور خودکار درخواست را تا حداکثر تعداد تکرار مجدد امتحان کند.
وقتی درخواست‌ها را دوباره امتحان می‌کنید، از یک خط‌مشی عقب‌نشینی نمایی استفاده کنید. برای مثال، اگر ابتدا 5 ثانیه قبل از اولین تلاش مجدد مکث کنید، می توانید 10 ثانیه بعد از دومین و 20 ثانیه بعد از تلاش مجدد سوم مکث کنید. عقب نشینی نمایی کمک می کند تا مطمئن شوید که API را خیلی تهاجمی فراخوانی نمی کنید.
خطاهای اعتبارسنجی معمولاً در درخواست‌های آغاز شده توسط کاربر رخ می‌دهد، جایی که کاربر ورودی نامعتبری را وارد کرده است. در این موارد، شما باید یک پیغام خطای مناسب را بر اساس خطای 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 را بازیابی می‌کند و پایگاه داده محلی را به‌روزرسانی می‌کند، سپس از کاربر می‌خواهد رابط کاربری را به‌روزرسانی کند.
برای درخواست‌های بک‌اند، برخی از خطاها اطلاعات کافی برای برنامه شما فراهم می‌کنند تا به‌طور خودکار و تدریجی پایگاه داده محلی شما را تصحیح کند. برای مثال، CANNOT_OPERATE_ON_REMOVED_ADGROUPAD باید باعث شود برنامه شما آن تبلیغ را به عنوان حذف شده در پایگاه داده محلی شما علامت گذاری کند. خطاهایی که نمی‌توانید به این روش مدیریت کنید، می‌تواند باعث شود برنامه شما کار همگام‌سازی کامل‌تری را راه‌اندازی کند یا به صفی برای بازبینی اپراتور انسانی اضافه شود.
تاریخ آخرین به‌روزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-03 بهوقت ساعت هماهنگ جهانی."],[[["\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."]]
