דף זה תורגם על ידי Cloud Translation API.

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

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

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