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

• ‫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.v24.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, וכך ליצור אפליקציות יציבות וידידותיות יותר למשתמשים.