סוגי שגיאות

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

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

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

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

שגיאות אימות

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

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

באופן דומה, אם לפרויקט שלכם ב-Google Cloud יש רק רמת גישה לבדיקה ואתם מנסים לשלוח בקשות לחשבון הפקה (לא חשבון בדיקה), ה-API מחזיר את השגיאה AuthorizationError, שערך ה-enum שלה תלוי בגרסת ה-API:

שגיאות שאפשר לנסות שוב

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

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

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

כשמנסים לשלוח שוב בקשות, כדאי להשתמש במדיניות של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם רעידות אקראיות. לדוגמה, אם אתם משהים את הפעולה למשך 5 שניות לפני הניסיון החוזר הראשון, אתם יכולים להשהות אותה למשך 10 שניות אחרי הניסיון החוזר השני ולמשך 20 שניות אחרי הניסיון החוזר השלישי. כדאי להוסיף לכל אינטרוול השהיה קצרה ואקראית כדי למנוע שיאים של ניסיונות חוזרים מסונכרנים. השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עוזרת לוודא שאתם לא קוראים ל-API בצורה אגרסיבית מדי. אם השגיאה נמשכת אחרי שכל הניסיונות החוזרים מוצו, צריך לרשום ביומן את request-id מהתגובה לצורך פתרון בעיות.

שגיאות אימות

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

הבא
הסבר על שגיאות API