סוגי שגיאות

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

• אימות
• אפשר לנסות שוב
• אימות
• בעיות שקשורות לסנכרון

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

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

שגיאות אימות

האימות מתייחס לשאלה אם משתמש נתן לאפליקציה הרשאה לגשת ל-Google Ads בשבילו. האימות מנוהל באמצעות פרטי כניסה שנוצרו על ידי תהליך OAuth2.

הסיבה הנפוצה ביותר לשגיאת אימות שנובעת מגורמים שאינם בשליטתכם היא שהמשתמש המאומת ביטל את ההרשאה שהוא נתן לאפליקציה לפעול בשבילו. לדוגמה, אם האפליקציה שלכם מנהלת חשבונות Google Ads נפרדים ללקוחות עצמאיים ומבצעת אימות בנפרד לכל לקוח כשמנהלים את החשבון שלו, הלקוח יכול לבטל את הגישה של האפליקציה בכל שלב. בהתאם למועד שבו הגישה בוטלה, ה-API עשוי להחזיר ישירות שגיאה מסוג AuthenticationError.OAUTH_TOKEN_REVOKED, או שאובייקטים מובנים של פרטי הכניסה בספריות הלקוח עשויים להוביל לחריגה מסוג אסימון שהתוקף שלו בוטל. בכל מקרה, אם לאפליקציה יש ממשק משתמש ללקוחות, אפשר לבקש מהם להפעיל מחדש את תהליך OAuth2 כדי לבסס מחדש את ההרשאה של האפליקציה לפעול בשמם.

שגיאות שניתן לנסות שוב

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

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

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

כשאתם מנסים לשלוח שוב בקשות, כדאי להשתמש במדיניות של השהיה מעריכית לפני ניסיון חוזר (exponential backoff). לדוגמה, אם תעצרו את הניסיון הראשון 5 שניות לפני הניסיון החוזר הראשון, תוכלו להשהות את הניסיון השני אחרי 10 שניות ואת הניסיון השלישי אחרי 20 שניות. השהיה מעריכית עוזרת לוודא שאתם לא קוראים ל-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 אמור לגרום לאפליקציה לסמן את המודעה הזו כ'הוסר' במסד הנתונים המקומי. שגיאות שלא ניתן לטפל בהן באופן הזה עלולות לגרום להפעלה של משימת סנכרון מקיפה יותר באפליקציה, או להוספה לתור לבדיקה על ידי צוות אנושי.