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

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

‫Google Ads API פועל לפי מודל השגיאות הרגיל של Google API, שמבוסס על קודי סטטוס של gRPC. כל תגובה מה-API שמובילה לשגיאה כוללת אובייקט Status שמכיל:

• קוד שגיאה מספרי.
• הודעת שגיאה.
• פרטי שגיאה נוספים (אופציונלי).

קודי שגיאה קנוניים

ב-Google Ads API נעשה שימוש בקבוצה של קודי שגיאה קנוניים שמוגדרים על ידי gRPC ו-HTTP. הקודים האלה מציינים באופן כללי את סוג השגיאה. תמיד כדאי לבדוק קודם את הקוד המספרי הזה כדי להבין את מהות הבעיה.

בטבלה הבאה מפורטים הקודים הנפוצים ביותר שאולי תיתקלו בהם כשמשתמשים ב-Google Ads API:

קוד gRPC	קוד HTTP	שם ה-enum	תיאור	הדרכה
0	200	OK	אין שגיאה, מציין הצלחה.	לא רלוונטי
1	499	CANCELLED	הפעולה בוטלה, בדרך כלל על ידי הלקוח.	בדרך כלל המשמעות היא שהלקוח הפסיק להמתין. בודקים את פסק הזמן בצד הלקוח.
2	500	UNKNOWN	קרתה שגיאה לא ידועה. יכול להיות שפרטים נוספים מופיעים בהודעת השגיאה או בפרטים.	התייחסות לשגיאה כשגיאת שרת. לרוב אפשר לנסות שוב עם השהיה.
3	400	INVALID_ARGUMENT	הלקוח ציין ארגומנט לא תקין. השגיאה הזו מציינת בעיה שמונעת מה-API לעבד את הבקשה, כמו שם משאב לא תקין או ערך לא תקין.	שגיאת לקוח: צריך לבדוק את פרמטרים הבקשה ולוודא שהם עומדים בדרישות ה-API. בפרטי השגיאה מופיע בדרך כלל מידע על הארגומנט הלא תקין ועל הסיבה לכך. אפשר להשתמש בפרטים האלה כדי לתקן את הבקשה. אל תנסו לשלוח את הבקשה שוב בלי לתקן אותה.
4	504	DEADLINE_EXCEEDED	המועד האחרון חלף לפני שהפעולה הסתיימה.	שגיאת שרת: לרוב זמנית. כדאי לנסות לשלוח שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
5	404	NOT_FOUND	לא נמצאה ישות מסוימת שביקשתם, כמו קמפיין או קבוצת מודעות.	שגיאת לקוח: צריך לוודא שהמשאבים שניסיתם לגשת אליהם קיימים ושיש להם מזהה. אל תנסו שוב בלי לתקן את הבעיה.
6	409	ALREADY_EXISTS	הישות שהלקוח ניסה ליצור כבר קיימת.	שגיאת לקוח: מומלץ להימנע מיצירת משאבים כפולים. לפני שמנסים ליצור משאב, צריך לבדוק אם הוא קיים.
7	403	PERMISSION_DENIED	למבצע הקריאה אין הרשאה להפעיל את הפעולה שצוינה.	שגיאת לקוח: צריך לבדוק את האימות, ההרשאה ותפקידי המשתמשים בחשבון Google Ads. אל תנסו שוב בלי לפתור את בעיית ההרשאות.
8	429	RESOURCE_EXHAUSTED	המשאב מוצה (לדוגמה, חרגתם מהמיכסה) או שהמערכת עמוסה מדי.	שגיאה בצד הלקוח או השרת: בדרך כלל צריך לחכות. כדאי להטמיע השהיה מעריכית לפני ניסיון חוזר (exponential backoff) ואולי להקטין את קצב הבקשות. מידע נוסף זמין במאמר בנושא מכסות ומגבלות של API.
9	400	FAILED_PRECONDITION	הפעולה נדחתה כי המערכת לא נמצאת במצב שנדרש לביצוע הפעולה. לדוגמה, חסר שדה חובה.	שגיאת לקוח: הבקשה תקינה, אבל הסטטוס שגוי. צריך לבדוק את פרטי השגיאה כדי להבין למה התנאי המקדים נכשל. אל תנסו שוב בלי לתקן את המצב.
10	409	ABORTED	הפעולה בוטלה, בדרך כלל בגלל בעיה של בו-זמניות (concurrency), כמו התנגשות בין טרנזקציות.	שגיאת שרת: בדרך כלל אפשר לנסות שוב אחרי השהיה קצרה.
11	400	OUT_OF_RANGE	הניסיון לבצע את הפעולה היה אחרי הטווח התקף.	שגיאה בצד הלקוח: צריך לתקן את הטווח או את האינדקס.
12	501	UNIMPLEMENTED	הפעולה לא הוטמעה או לא נתמכת על ידי ה-API.	שגיאת לקוח: צריך לבדוק את גרסת ה-API ואת התכונות הזמינות. לא לנסות שוב.
13	500	INTERNAL	אירעה שגיאה פנימית. זוהי בעיה כללית שקשורה לצד השרת.	שגיאה בחיבור לשרת: בדרך כלל אפשר לנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). אם הבעיה נמשכת, אפשר לדווח עליה.
14	503	UNAVAILABLE	השירות לא זמין כרגע. הסיבה לכך היא כנראה מצב זמני.	שגיאת שרת: מומלץ מאוד לנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
15	500	DATA_LOSS	פגם בנתונים או אובדן נתונים שלא ניתן לשחזר.	שגיאה בחיבור לשרת: נדירה. מציין בעיה חמורה. לא לנסות שוב. אם הבעיה נמשכת, אפשר לדווח עליה.
16	401	UNAUTHENTICATED	בבקשה לא צוינו פרטי כניסה תקינים לאימות.	שגיאת לקוח: צריך לאמת את אסימוני האימות ואת פרטי הכניסה. לא לנסות שוב בלי לתקן את האימות.

פרטים נוספים על הקודים האלה זמינים במאמר מדריך לעיצוב API – קודי שגיאה.

הסבר על פרטי השגיאה

בנוסף לקוד ברמה העליונה, Google Ads API מספק מידע ספציפי יותר על שגיאות בשדה details של האובייקט Status. השדה הזה מכיל לרוב פרוטו של GoogleAdsFailure, שכולל רשימה של אובייקטים בודדים של GoogleAdsError.

כל אובייקט GoogleAdsFailure מכיל:

• ‫errors: רשימה של אובייקטים מסוג GoogleAdsError, שכל אחד מהם מפרט שגיאה ספציפית שהתרחשה.
• ‫request_id: מזהה ייחודי של הבקשה, שימושי למטרות ניפוי באגים ותמיכה.

כל אובייקט GoogleAdsError מספק:

• ‫error_code: שגיאה ספציפית יותר ל-Google Ads API ErrorCode (שגיאות נפוצות), כמו AuthenticationError.NOT_ADS_USER.
• ‫message: תיאור של השגיאה הספציפית שכתוב בצורה שקריאה לאנשים.
• ‫trigger: Value שגרם לשגיאה, אם רלוונטי.
• ‫location: ErrorLocation שמתאר איפה בבקשה התרחשה השגיאה, כולל נתיבי השדות.
• ‫details: פרטים נוספים על ErrorDetails, כמו סיבות לשגיאות שלא פורסמו.

דוגמה לפרטי שגיאה

כשמתקבלת שגיאה, ספריית הלקוח מאפשרת לגשת לפרטים האלה. לדוגמה, קוד INVALID_ARGUMENT (Code 3) יכול לכלול פרטים כמו אלה:GoogleAdsFailure

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v25.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

בדוגמה הזו, למרות שמוצגת השגיאה ברמה העליונה INVALID_ARGUMENT, הפרטים של GoogleAdsFailure מציינים שהשדות name ו-description גרמו לבעיה, ומסבירים למה (REQUIRED ו-TOO_SHORT, בהתאמה).

איפה אפשר לראות את פרטי השגיאה

הגישה לפרטי השגיאה תלויה בשאלה אם אתם משתמשים בקריאות API רגילות, בכשל חלקי או בסטרימינג.

קריאות ל-API רגילות וקריאות ל-API של סטרימינג

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

כשל חלקי

אם אתם משתמשים בכשל חלקי, השגיאות של פעולות שנכשלו מוחזרות בשדה partial_failure_error של התגובה, ולא בכותרות התגובה. במקרה הזה, האובייקט GoogleAdsFailure מוטמע באובייקט google.rpc.Status בתשובה.

משימות באצווה

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

מזהה בקשה

‫request-id היא מחרוזת ייחודית שמזהה את בקשת ה-API שלכם, והיא חיונית לפתרון בעיות.

אפשר למצוא את request-id בכמה מקומות:

• ‫GoogleAdsFailure: אם קריאה ל-API נכשלת ומוחזרת GoogleAdsFailure, היא תכיל request_id.
• מטא-נתונים מסוג trailing: גם בבקשות שהצליחו וגם בבקשות שנכשלו, request-id זמין במטא-נתונים מסוג trailing של תגובת gRPC.
• כותרות תגובה: גם במקרה של בקשות שהצליחו וגם במקרה של בקשות שנכשלו, request-id זמין בכותרות התגובה של gRPC ו-HTTP, למעט במקרה של בקשות סטרימינג שהצליחו.
• ‫SearchGoogleAdsStreamResponse: בבקשות סטרימינג, כל הודעה SearchGoogleAdsStreamResponse מכילה שדה request_id.

כשרושמים שגיאות ביומן או פונים לתמיכה, חשוב לכלול את request-id כדי לעזור באבחון בעיות.

שיטות מומלצות לטיפול בשגיאות

כדי ליצור אפליקציות עמידות, כדאי להטמיע את השיטות המומלצות הבאות:

1. בדיקת פרטי השגיאה: תמיד צריך לנתח את השדה details של האובייקט Status, ובמיוחד לחפש את GoogleAdsFailure. הנתונים המפורטים error_code, message ו-location בתוך GoogleAdsError מספקים את המידע הכי שימושי לניפוי באגים ולמשוב משתמשים.

2. הבחנה בין שגיאות בצד הלקוח לבין שגיאות בצד השרת:

   • שגיאות בצד הלקוח: קודים כמו INVALID_ARGUMENT, NOT_FOUND,‏ PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. כדי לפתור את הבעיות האלה, צריך לשנות את הבקשה או את מצב האפליקציה או את פרטי הכניסה שלה. אל תנסו לשלוח את הבקשה שוב בלי לפתור את הבעיה.
   • שגיאות בחיבור לשרת: קודים כמו UNAVAILABLE, ‏INTERNAL, ‏DEADLINE_EXCEEDED, ‏UNKNOWN. ההודעות האלה מצביעות על בעיה זמנית בשירות ה-API.

3. הטמעה של אסטרטגיה של ניסיון חוזר:

   • מתי כדאי לנסות שוב: כדאי לנסות שוב רק במקרה של שגיאות שרת זמניות כמו UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN ו-ABORTED.
   • השהיה מעריכית לפני ניסיון חוזר (exponential backoff): צריך להשתמש באלגוריתם של השהיה מעריכית לפני ניסיון חוזר כדי להמתין פרקי זמן ארוכים יותר בין ניסיונות חוזרים. כך אפשר למנוע עומס יתר על שירות שכבר נמצא במצב של עומס. לדוגמה, צריך להמתין שנייה אחת, אחר כך שתי שניות, אחר כך ארבע שניות, ולהמשיך כך עד שמגיעים למספר המקסימלי של ניסיונות חוזרים או לזמן ההמתנה הכולל.
   • רעידות: מוסיפים כמות קטנה ואקראית של 'רעידות' להשהיות של ההשהיה לפני ניסיון חוזר (backoff) כדי למנוע את בעיית 'העדר הרועם', שבה לקוחות רבים מנסים שוב בו-זמנית.

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

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

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