הסבר על שגיאות 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	הפעולה בוטלה, בדרך כלל בגלל בעיה של פעולות מקבילות, כמו התנגשות בין טרנזקציות.	שגיאת שרת: בדרך כלל אפשר לנסות שוב אחרי השהיה קצרה.
11	400	OUT_OF_RANGE	הניסיון לבצע את הפעולה היה אחרי הטווח התקף.	שגיאת לקוח: צריך לתקן את הטווח או האינדקס.
12	501	UNIMPLEMENTED	הפעולה לא הוטמעה או לא נתמכת על ידי ה-API.	שגיאת לקוח: צריך לבדוק את גרסת ה-API ואת התכונות הזמינות. לא לנסות שוב.
13	500	INTERNAL	אירעה שגיאה פנימית. זוהי קטגוריה כללית לבעיות בצד השרת.	שגיאת שרת: בדרך כלל אפשר לנסות שוב עם השהיה מעריכית לפני ניסיון חוזר. אם הבעיה נמשכת, אפשר לדווח עליה.
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 מספק את הפרטים הבאים:

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

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

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

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

בדוגמה הזו, למרות 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 בתשובה.

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

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