סוגי שגיאות

סיווגנו את השגיאות לקטגוריות הכלליות הבאות:

• אימות
• ניתן לניסיון חוזר
• אימות
• קשור לסנכרון

הקטגוריות האלה לא כוללות את כל השגיאות האפשריות, ויכול להיות שחלק מהשגיאות יתאימו ליותר מקטגוריה אחת. עם זאת, הן יכולות לשמש כנקודת התחלה לבניית הטיפול בשגיאות באפליקציה. במקורות המידע הבאים אפשר למצוא פרטים נוספים על שגיאות ספציפיות:

• בקטע שגיאות נפוצות מפורטים פרטים נוספים על שגיאה מסוימת.
• ‫google.rpc.Status לפרטים על מודל השגיאות הלוגי שבו נעשה שימוש ב-API.
• קודי שגיאה קנוניים לרשימה ולהסבר של קודי שגיאה קנוניים שמוגדרים על ידי gRPC ו-HTTP בהקשר של Google Ads API.

שגיאות אימות

אימות הוא תהליך שבו משתמש מעניק לאפליקציה הרשאה לגשת לחשבון 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 אמור לגרום לאפליקציה לסמן את המודעה הזו כמודעה שהוסרה במסד הנתונים המקומי. שגיאות שלא ניתן לטפל בהן בדרך הזו עלולות לגרום להפעלת משימת סנכרון מלאה יותר באפליקציה, או להוספת האפליקציה לתור לבדיקה על ידי מפעיל אנושי.