‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.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.
מטא-נתונים נגררים: גם לבקשות שהצליחו וגם לבקשות שנכשלו, הערך request-id זמין במטא-נתונים הנגררים של התגובה ב-gRPC.
כותרות תגובה: בבקשות שהצליחו ובבקשות שנכשלו, הערך של request-id זמין גם בכותרות התגובה של gRPC ובתגובות HTTP, חוץ מבקשות סטרימינג שהצליחו.
‫SearchGoogleAdsStreamResponse: בבקשות סטרימינג, כל הודעת SearchGoogleAdsStreamResponse מכילה שדה request_id.

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

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

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

בדיקת פרטי השגיאה: תמיד צריך לנתח את השדה details של האובייקט Status, במיוחד כדי לחפש את GoogleAdsFailure. השדות המפורטים error_code,‏ message ו-location ב-GoogleAdsError מספקים את המידע הכי שימושי לניפוי באגים ולמשוב ממשתמשים.
הבחנה בין שגיאות בצד הלקוח לשגיאות בחיבור לשרת:
- שגיאות בצד הלקוח: קודים כמו INVALID_ARGUMENT,‏ NOT_FOUND,‏ PERMISSION_DENIED,‏ FAILED_PRECONDITION,‏ UNAUTHENTICATED. כדי לפתור אותן, צריך לשנות את הבקשה או את המצב או פרטי הכניסה של האפליקציה. אל תנסו לשלוח שוב את הבקשה בלי לטפל בבעיה.
- שגיאות בחיבור לשרת: קודים כמו UNAVAILABLE,‏ INTERNAL,‏ DEADLINE_EXCEEDED,‏ UNKNOWN. השגיאות האלה מצביעות על בעיה זמנית בשירות ה-API.
הטמעת אסטרטגיה של ניסיון חוזר:
- מתי לנסות שוב: נסו שוב רק במקרה של שגיאות זמניות בחיבור לשרת, כמו UNAVAILABLE,‏ DEADLINE_EXCEEDED,‏ INTERNAL,‏ UNKNOWN ו-ABORTED.
- השהיה מעריכית לפני ניסיון חוזר (exponential backoff): משתמשים באלגוריתם של השהיה מעריכית לפני ניסיון חוזר כדי להמתין פרקי זמן הולכים וגדלים בין הניסיונות החוזרים. כך אפשר למנוע עומס יתר על שירות שכבר עמוס. לדוגמה, ממתינים שנייה אחת, אחר כך 2 שניות, אחר כך 4 שניות, עד שמגיעים למספר המקסימלי של ניסיונות חוזרים או לזמן ההמתנה הכולל.
- ריצוד: מוסיפים כמות קטנה ואקראית של "ריצוד" להשהיות של השהיית הניסיון החוזר, כדי למנוע את בעיית "העדר הרועם" שבה הרבה לקוחות מנסים שוב בו-זמנית.
רישום מפורט ביומן: רישום של תגובת השגיאה המלאה, כולל כל הפרטים, במיוחד מזהה הבקשה. המידע הזה חיוני לניפוי באגים ולדיווח על בעיות לתמיכה של Google במקרה הצורך.
לספק משוב למשתמשים: על סמך הקודים וההודעות הספציפיים של GoogleAdsError, לספק משוב ברור ומועיל למשתמשים באפליקציה. לדוגמה, במקום "אירעה שגיאה", אפשר לכתוב "צריך לציין את שם הקמפיין" או "מזהה קבוצת המודעות שצוין לא נמצא".

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

סוגי שגיאות

שגיאות נפוצות

הסבר על שגיאות API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.