خطاها را در دسته‌های کلی زیر طبقه‌بندی کرده‌ایم:
- اصالت‌سنجی
- خطاهایی که می‌توان دوباره امتحان کرد
- اعتبارسنجی
- مرتبط با همگام‌سازی
اگرچه این دسته‌ها شامل همه خطاهای احتمالی نمی‌شوند و برخی ممکن است در بیش‌از یک دسته قرار بگیرند، بااین‌حال می‌توانند به‌عنوان نقطه شروعی برای ساختاردهی به مدیریت خطای برنامه‌تان عمل کنند. برای جزئیات بیشتر درباره خطاهای خاص، منابع زیر را ببینید:
- خطاهای رایج جزئیات بیشتری درباره خطای خاصی ارائه می‌دهد.
google.rpc.Statusجزئیاتی درباره مدل خطای منطقی مورداستفاده میانای برنامه‌سازی کاربردی ارائه می‌دهد.- کدهای خطای متعارف فهرستی از کدهای خطای متعارف تعریف‌شده توسط gRPC و HTTP در بافت Google Ads API را به‌همراه توضیح آن‌ها ارائه می‌دهد.
خطاهای اصالت‌سنجی
اصالت‌سنجی به این اشاره دارد که آیا کاربر به برنامه شما اجازه داده است که ازطرف او به Google Ads دسترسی داشته باشد یا نه. اصالت‌سنجی ازطریق اطلاعات اعتباری تولیدشده توسط جریان OAuth2 مدیریت می‌شود.
رایج‌ترین دلیل بروز خطای اصالت‌سنجی ناشی از عوامل خارج از کنترل شما این است که کاربر اصالت‌سنجی‌شده اجازه‌ای را که به برنامه شما برای اقدام ازطرف او داده بود لغو کرده است. برای مثال، اگر برنامه‌تان حساب‌های Google Ads جداگانه‌ای را برای مشتریان مستقل مدیریت می‌کند و هنگام مدیریت حساب هر مشتری، به‌طور جداگانه به‌عنوان آن مشتری اصالت‌سنجی می‌کند، مشتری می‌تواند در هرزمانی دسترسی برنامه‌تان را لغو کند. بسته به اینکه دسترسی شما چه زمانی لغو شده است، میانای برنامه‌سازی کاربردی ممکن است مستقیماً
خطای AuthenticationError.OAUTH_TOKEN_REVOKED را برگرداند، یا
اشیاء اعتبارنامه داخلی در کتابخانه‌های کارخواه ممکن است
استثنای لغو کد را ایجاد کنند. در هر دو مورد، اگر برنامه‌تان واسط کاربری برای مشتریانتان دارد، می‌تواند از آن‌ها بخواهد جریان OAuth2 را مجدداً راه‌اندازی کنند تا اجازه برنامه‌تان برای اقدام ازطرف آن‌ها دوباره برقرار شود.
به‌طور مشابه، اگر پروژه Google Cloud شما فقط سطح دسترسی آزمایشی داشته باشد و تلاش کند درخواست‌هایی را برای حساب تولید (غیرآزمایشی) ارسال کند، API یک AuthorizationError برمی‌گرداند که مقدار شمارشی آن به نسخه API بستگی دارد:
- شروع در
v25: برمی‌گرددAuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION. v24و نسخه‌های قدیمی‌تر:AuthorizationError.ACTION_NOT_PERMITTEDرا برمی‌گرداند.
خطاهایی که می‌توان دوباره امتحان کرد
برخی‌از خطاها، مانند TRANSIENT_ERROR یا
INTERNAL_ERROR، می‌توانند نشان‌دهنده مشکلی موقتی باشند که ممکن است
با امتحان مجدد درخواست پس‌از وقفه‌ای کوتاه برطرف شود.
برای درخواست‌های آغازشده توسط کاربر، یک راهبرد این است که فوراً خطایی را در میانای کاربر نشان دهید و به کاربر گزینه‌ای برای شروع مجدد بدهید. یا اینکه برنامه‌تان می‌تواند ابتدا به‌طور خودکار درخواست را دوباره امتحان کند و فقط پس‌از رسیدن به حداکثر تعداد دفعات امتحان مجدد یا کل زمان انتظار کاربر، خطا را در میانای کاربر نشان دهد.
برای درخواست‌هایی که در پس‌نما شروع شده‌اند، برنامه‌تان باید به‌طور خودکار درخواست را تا حداکثر تعداد تلاش مجدد تکرار کند.
هنگام امتحان مجدد درخواست‌ها، از خط‌مشی عقب‌نشینی نمایی با لرزش تصادفی استفاده کنید. برای مثال، اگر ابتدا ۵ ثانیه قبل‌از اولین تلاش مجدد مکث کنید، می‌توانید ۱۰ ثانیه بعداز تلاش مجدد دوم و ۲۰ ثانیه بعداز تلاش مجدد سوم مکث کنید و تأخیر تصادفی کوچکی به هر فاصله اضافه کنید تا از جهش‌های تلاش مجدد همگام‌سازی‌شده جلوگیری شود. عقب‌نشینی نمایی کمک می‌کند مطمئن شوید که API را بیش‌ازحد تهاجمی فراخوانی نمی‌کنید. اگر پس‌از اتمام تلاش‌های مجدد، خطا همچنان ادامه داشت،
request-id را از پاسخ برای عیب‌یابی ثبت کنید.
خطاهای اعتبارسنجی
خطاهای اعتبارسنجی نشان می‌دهد که ورودی عملیات قابل‌قبول نبوده است.
نمونه‌ها شامل PolicyViolationError،
DateError، DateRangeError،
StringLengthError، و
UrlFieldError است.
خطاهای اعتبارسنجی معمولاً در درخواست‌های آغازشده توسط کاربر رخ می‌دهد، جایی که کاربر ورودی نامعتبری وارد کرده است. در این موارد، باید براساس خطای خاص میانای برنامه‌سازی کاربردی که دریافت کرده‌اید، پیام خطای مناسبی به کاربر ارائه دهید. همچنین می‌توانید ورودی کاربر را قبل‌از برقراری تماس 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
باید باعث شود برنامه‌تان آن آگهی را در پایگاه داده محلی‌تان به‌عنوان برداشته‌شده علامت‌گذاری کند. خطاهایی
که نمی‌توانید به این روش مدیریت کنید ممکن است باعث شود برنامه‌تان کار همگام‌سازی کامل‌تری را راه‌اندازی کند یا به صف بررسی اپراتور انسانی اضافه شود.