סוגי שגיאות

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

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

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

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

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

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

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

שגיאות אימות

שגיאות אימות מצביעות על כך שקלט לפעולה לא היה קביל. לדוגמה: PolicyViolationError,‏ DateError,‏ DateRangeError,‏ StringLengthError ו-UrlFieldError.

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

באפליקציות רבות של 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