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

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

סקירה כללית

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

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

.

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

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

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

• ‫domain: הקיבוץ הלוגי של השגיאה, בדרך כלל merchantapi.googleapis.com.
• מטא-נתונים: מפה של ערכים דינמיים שקשורים לשגיאה. אפשר להציג מודעות ב:
  • ‫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 keys: המפתחות במיפוי המטא-נתונים (לדוגמה, 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)

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

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

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

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

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

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