סווגנו את השגיאות לקטגוריות הכלליות הבאות:
- אימות
- ניסיון חוזר
- אימות
- קשור לסנכרון
הקטגוריות האלה לא כוללות את כל השגיאות האפשריות, וחלקן יכולות להתאים ליותר מקטגוריה אחת, אבל הן בכל זאת יכולות לשמש כנקודת התחלה לארגון הטיפול בשגיאות של האפליקציה. פרטים נוספים על שגיאה מסוימת מופיעים במאמר שגיאות נפוצות.
שגיאות אימות
אימות מתייחס אם האפליקציה קיבלה הרשאה ממשתמש לגשת ל-Google Ads בשמו. האימות מנוהל באמצעות פרטי הכניסה שנוצרים על ידי תהליך OAuth2.
הסיבה הנפוצה ביותר ששגיאת אימות נובעת מגורמים שלא בשליטתכם היא שהמשתמש המאומת ביטל את ההרשאה שהוא נתן לאפליקציה לפעול בשמו. לדוגמה, אם האפליקציה מנהלת חשבונות Google Ads נפרדים ללקוחות עצמאיים ומבצעת אימות בנפרד בתור כל לקוח בזמן ניהול החשבון של אותו לקוח, לקוח יכול לבטל את הגישה של האפליקציה בכל שלב. בהתאם למועד שבו הגישה בוטלה, ה-API עשוי להחזיר ישירות את שגיאת AuthenticationError.OAUTH_TOKEN_REVOKED, או שהאובייקטים המובנים של פרטי הכניסה בספריות הלקוח עלולים לגרום לחריגה מביטול האסימון. בכל מקרה, אם לאפליקציה יש ממשק משתמש עבור הלקוחות, הוא יכול לבקש מהם להפעיל מחדש את תהליך OAuth2 כדי לחדש את ההרשאה לאפליקציה לפעול בשמם.
שגיאות שמאפשרות ניסיון חוזר
שגיאות מסוימות, כמו TRANSIENT_ERROR
או INTERNAL_ERROR,
יכולות להצביע על בעיה זמנית שאפשר לפתור באמצעות ניסיון חוזר
של הבקשה לאחר השהיה קצרה.
בבקשות שיזמו את המשתמשים, דרך אחת היא לציין באופן מיידי שגיאה בממשק המשתמש ולתת למשתמש אפשרות להפעיל ניסיון חוזר. לחלופין, תחילה האפליקציה תוכל לנסות מחדש את הבקשה באופן אוטומטי, רק אחרי שהיא תחשוף את השגיאה בממשק המשתמש אחרי שהיא תגיע למספר הניסיונות החוזרים המקסימלי או לאחר סך זמן ההמתנה של המשתמש.
לבקשות שנשלחות בקצה העורפי, האפליקציה צריכה לבצע ניסיון חוזר של הבקשה באופן אוטומטי, עד למספר המקסימלי של ניסיונות חוזרים.
כשמבצעים ניסיון חוזר של בקשות, צריך להשתמש במדיניות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). לדוגמה, אם החלטתם להשהות את התהליך 5 שניות לפני הניסיון הראשון, תוכלו להשהות אותו 10 שניות אחרי הניסיון השני ו-20 שניות אחרי הניסיון השלישי. השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עוזרת לוודא שאתם לא שולחים קריאה אגרסיבית מדי ל-API.
שגיאות אימות
שגיאות אימות מציינות שקלט לפעולה לא היה קביל.
לדוגמה, PolicyViolationError,
DateError,
DateRangeError,
StringLengthError וגם
UrlFieldError.
שגיאות אימות מתרחשות בדרך כלל בבקשות ביוזמת משתמשים, שבהן המשתמש הזין קלט לא חוקי. במקרים כאלה צריך לספק למשתמש הודעת שגיאה מתאימה בהתאם לשגיאת ה-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 צריך לגרום לאפליקציה לסמן את המודעה כ'הוסרה' במסד הנתונים המקומי. שגיאות שאי אפשר לטפל בהן בדרך הזו עלולות לגרום לאפליקציה להפעיל משימת סנכרון מלאה יותר או להתווסף לתור לבדיקה של מפעיל אנושי.