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

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

סקירה כללית

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

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

תגובת השגיאה היא אובייקט 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).

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

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

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