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

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

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

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

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