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

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

סקירה כללית

כשבקשת Merchant API נכשלת, ה-API מחזיר קוד סטטוס HTTP סטנדרטי (4xx או 5xx) וגוף תגובה בפורמט JSON שמכיל פרטים על השגיאה. ‫Merchant API פועל לפי תקן AIP-193 לפרטי שגיאות, ומספק מידע בפורמט קריא למכונה שמאפשר לאפליקציה לטפל בתרחישי שגיאה ספציפיים באופן פרוגרמטי.

הערה: אנחנו משיקים את מבנה התגובה הזה לשגיאות בהדרגה ב-Merchant API. רק שגיאות שמוחזרות על ידי ממשקי ה-API המשניים Products, ‏ Reports ו-Data sources תואמות לפורמט שמתואר כאן. יכול להיות ששגיאות מממשקי API משניים אחרים עדיין יהיו בפורמט מדור קודם, ולא יכללו את המטא-נתונים של ErrorInfo.

מבנה התגובה לשגיאה

תגובת השגיאה היא אובייקט JSON שמכיל שדות סטנדרטיים כמו code, message ו-status. חשוב לציין שהוא כולל גם מערך details. כדי לטפל בשגיאות באופן פרוגרמטי, צריך לחפש אובייקט בתוך details שבו הערך של @type הוא type.googleapis.com/google.rpc.ErrorInfo.

האובייקט ErrorInfo מספק נתונים יציבים ומובְנים על השגיאה:

• ‫domain: הקבוצה הלוגית של השגיאה, בדרך כלל merchantapi.googleapis.com.
• ‫metadata: מפה של ערכים דינמיים שקשורים לשגיאה. אפשר להציג מודעות ב:
  • ‫REASON: מזהה ספציפי ויציב של השגיאה המדויקת (למשל, INVALID_NAME_PART_NOT_NUMBER,‏ PERMISSION_DENIED_ACCOUNTS). השדה הזה תמיד מופיע. אפשר להשתמש בשדה הזה כדי לטפל בשגיאות בצורה מפורטת בלוגיקה של האפליקציה.
  • ‫HELP_CENTER_LINK: הקשר נוסף והוראות לפתרון הבעיה. השדה הזה לא מופיע בכל השגיאות, אבל אנחנו מתכננים להרחיב את הכיסוי שלו עם הזמן לשגיאות שבהן יכול להיות שצריך הקשר נוסף.
  • שדות דינמיים אחרים: מפתחות אחרים שמספקים הקשר, כמו שם השדה הלא תקין (FIELD_LOCATION) או הערך שגרם לשגיאה (FIELD_VALUE).

תגובות שגיאה לדוגמה

קוד ה-JSON הבא מדגים את המבנה של שגיאת Merchant API שבה שם המשאב לא תקין.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

דוגמה לשגיאת אימות:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

יציבות של שדות שגיאה

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

• שדות יציבים:

• ‫details.metadata.REASON: המזהה הספציפי של השגיאה. כדאי להסתמך על השדה הזה בשביל לוגיקת זרימת הבקרה של האפליקציה.

  • מפתחות details.metadata: המפתחות במפת המטא-נתונים (למשל, FIELD_LOCATION,‏ ACCOUNT_IDS) הם קבועים.
  • ‫code: קוד הסטטוס של HTTP ברמה הגבוהה (למשל, 400,‏ 401,‏ 503) יציב.

• שדות לא יציבים:

  • ‫message: הודעת השגיאה הקריאה לאנשים לא יציבה. הוא מיועד לניפוי באגים של מפתחים בלבד. אל תכתבו קוד שמנתח את תוכן הטקסט של השדה message או מסתמך עליו, כי הוא עשוי להשתנות ללא הודעה מוקדמת כדי לשפר את הבהירות או להוסיף הקשר.
  • ערכי details.metadata: המפתחות יציבים, אבל הערכים של מפתחות המידע עשויים להשתנות. לדוגמה, אם מסופק מפתח HELP_CENTER_LINK, יכול להיות שכתובת ה-URL הספציפית שהוא מפנה אליה תעודכן לדף תיעוד חדש יותר בלי הודעה מוקדמת. אבל כמו שציינו קודם, הערך של details.metadata.REASON יציב.

שיטות מומלצות

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

שימוש ב-details.metadata.REASON ללוגיקה

כדי לזהות את הגורם לשגיאה, תמיד צריך להשתמש ב-REASON הספציפי בתוך המפה metadata. אל תסתמכו רק על קוד הסטטוס של HTTP, כי יכול להיות שלכמה שגיאות יהיה אותו קוד סטטוס.

אל תנתחו את הודעת השגיאה

כפי שצוין בקטע בנושא יציבות, השדה message מיועד לשימוש אנושי. אם אתם צריכים מידע דינמי (כמו איזה שדה לא היה תקין), חלצו אותו מהמפה metadata באמצעות מפתחות יציבים כמו FIELD_LOCATION, VARIABLE_NAME.

הטמעת השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

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

• ‫quota/request_rate_too_high: השגיאה הזו מציינת שחרגתם מהמכסה לדקה של קבוצת מכסות ספציפית. להאט את קצב הבקשות.
• ‫internal_error: בדרך כלל מדובר בשגיאות זמניות. צריך לנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

הערה: אם השגיאה internal_error נמשכת אחרי כמה ניסיונות חוזרים עם השהיה, אפשר לעיין במאמר איך לפנות לתמיכה של Merchant API.

איך פונים לתמיכה של Merchant API

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

1. תגובת השגיאה המדויקת שהתקבלה
2. שם ה-method של ה-API
3. המטען הייעודי (payload) של הבקשה
4. חותמות זמן או טווח תאריכים שבו בוצעה הקריאה ל-method והתקבלו השגיאות