קודי שגיאה

בדף הזה מפורטים קודי השגיאה הקנוניים שצריך להחזיר בתגובות ה-API כשמשתמשים ב-Universal Commerce Protocol‏ (UCP) כדי לבצע שילוב עם Google. קודים עקביים של שגיאות מבטיחים תקשורת ברורה ועוזרים ל-Google לטפל בתרחישים שונים בצורה הולמת.

כשמתרחשת שגיאה בעסק, ה-API צריך להחזיר הודעת תגובה שכוללת את code המתאים מהטבלה. לגבי חלק מקודי השגיאה, מומלץ להשתמש במבנה JSON ספציפי למערך messages בתגובה. הדוגמאות האלה מופיעות בקטע דוגמאות לקודי שגיאה שמתחת לטבלה. בדוגמאות האלה, צריך להשתמש בשדה path כדי לספק מידע ספציפי יותר על מיקום השגיאה באובייקט הבקשה או התגובה.

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

אופן הדיווח על שגיאות תלוי בסוג השגיאה:

  • שגיאות בפרוטוקול או בשרת:

    • משתמשים בקודי סטטוס רגילים של HTTP (למשל, 4xx לשגיאות לקוח, 5xx לשגיאות שרת) לבעיות כמו בקשות לא תקינות, כשלים באימות או חוסר זמינות של השרת.
    • פרטים נוספים מפורטים במפרט של UCP.

  • שגיאות או אזהרות של לוגיקה עסקית:

    • להחזיר סטטוס HTTP 200 OK. זה כולל דחיות של תשלומים ודחיות של תשלומים בגלל הונאה, גם אם שער התשלומים במורד הזרם מחזיר שגיאת 4xx או 5xx.
    • מתארים את הבעיה במערך messages בגוף תגובת ה-JSON.
    • כל אובייקט במערך messages חייב לכלול:
      • type: "error" או "warning"
      • ‫code: קוד סטנדרטי מהמדריך הזה. אל תשתמשו בקודים כלליים או לא מוכרים כמו "invalid".
      • ‫content: תיאור שקריא לאנשים.
      • ‫severity: חובה אם הערך של type הוא "error". השדה הזה מציין באופן מפורש אם השגיאה היא סופית (unrecoverable) או מאפשר לכם להציג לקונה הנחיה לתיקון הבעיה (recoverable), במקום להסתמך על קוד השגיאה עצמו.

סוגי הודעות: שגיאה לעומת אזהרה

השדה type במערך ההודעות מציין את חומרת הבעיה. ב-UCP מוגדרים שני סוגים עיקריים:

  • ‫error: מציין שלא ניתן היה להשלים את הפעולה המבוקשת. המשתמש או הפלטפורמה כנראה יצטרכו לבצע פעולה ולנסות שוב. מפרט הודעת השגיאה
    • האם השגיאה היא סופית נקבע לפי השדה severity (unrecoverable או recoverable), ולא לפי השגיאה code.
  • ‫warning: מציין שהפעולה לא נחסמה, אבל יש משהו חשוב שצריך להעביר למשתמש. התהליך לא נעצר, אבל ההסבר מספק הקשר חשוב. מפרט אזהרות לגבי הודעות

הפניה לקוד השגיאה

קוד שגיאה סוג מומלץ תיאור
out_of_stock שגיאה הפריט לא זמין. בדרך כלל התוצאה היא ucp.status: “error”. משתמשים בשדה path כדי לציין את אינדקס הפריט בתהליכי תשלום עם כמה פריטים. דוגמה
item_unavailable שגיאה לא ניתן למצוא את הפריט. בדרך כלל, השגיאות שקשורות לפריטים מקבלות את הערך ucp.status: “error”.
item_ineligible שגיאה הפריט קיים אבל אי אפשר לרכוש אותו באמצעות UCP.
quantity_invalid_limit_exceeded שגיאה הכמות המבוקשת חורגת מהמגבלה המותרת. דוגמה
quantity_invalid_minimum_not_met שגיאה הכמות המבוקשת נמוכה מהכמות המינימלית הנדרשת.
totals_changed אזהרה המחיר או סכומים אחרים השתנו מאז השלב האחרון. משתמשים בשדה path כדי לציין איזה סכום כולל השתנה. דוגמה
totals_invalid_minimum_not_met שגיאה ערך ההזמנה לא מגיע למינימום הנדרש.
missing_buyer_info שגיאה חסרים פרטים נדרשים של הקונה. משתמשים בשדה path כדי לציין את השדה החסר. דוגמה
address_undeliverable שגיאה זהו קוד שגיאה רגיל של UCP. משתמשים בשדה path כדי לציין את היעד הספציפי או את הפריט המוגבל. דוגמה
address_unverifiable שגיאה לא הצלחנו לאמת את הכתובת שציינת. בשדה path מציינים אם זו כתובת למשלוח או לחיוב. דוגמה
missing_fulfillment_info שגיאה חסר מידע חובה על אספקת המוצר. משתמשים בשדה path כדי לציין את השדה החסר.
eligibility_invalid שגיאה המשתמש או ההזמנה לא כשירים לפעולה. זהו קוד שגיאה רגיל של UCP. משתמשים בשדה path כדי לציין פרטים ספציפיים.
discount_code_invalid אזהרה קוד ההנחה לא תקף. הקוד לא נמצא או שהפורמט שלו שגוי.
discount_code_expired אזהרה פג התוקף של קוד ההנחה.
discount_code_already_applied אזהרה קוד ההנחה כבר מומש.
discount_code_combination_disallowed אזהרה אי אפשר לשלב את קוד ההנחה עם מבצעים אחרים.
discount_code_user_not_logged_in אזהרה כדי להשתמש בקוד ההנחה, המשתמשים צריכים להתחבר לחשבון שלהם.
discount_code_user_ineligible אזהרה המשתמש לא כשיר לשימוש בקוד ההנחה.
missing_billing_info שגיאה חסרים פרטי חיוב שחובה לציין. משתמשים בשדה path כדי לציין את השדות החסרים של כתובת לחיוב. דוגמה
identity_required שגיאה נדרש זיהוי משתמש לפעולה המבוקשת, אבל הוא לא קיים, לא תקין, לא בתוקף או שלא ניתן לאמת אותו. ב-REST, משתמשים בקוד סטטוס 401. דוגמה
insufficient_scope שגיאה טוקן זהות המשתמש תקין, אבל חסרות בו ההיקפים שנדרשים לפעולה. ב-REST, משתמשים בקוד סטטוס 403. דוגמה
payment_declined שגיאה התשלום נדחה על ידי מנפיק הכרטיס או הבנק. הסיבות לכך יכולות להיות יתרה לא מספיקה, חשד להונאה או בעיות בכרטיס. דוגמה
payment_failed שגיאה התשלום נכשל בגלל בעיה טכנית במהלך העיבוד – כמו שגיאה בחיבור לרשת, פסק זמן בשער או בעיה בשילוב – שמנעה מהבנק להגיע להחלטה.
payment_ineligible שגיאה אמצעי התשלום שנבחר לא מתקבל. מתאים למקרים שבהם המשתמש צריך לנסות אמצעי תשלום אחר.
rejected_for_fraud שגיאה ההזמנה נדחתה בגלל חשד להונאה. דוגמה

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

בקטע הזה מופיעות דוגמאות ל-JSON של מערך messages עבור קודי שגיאה ספציפיים.

out_of_stock

תהליך תשלום על פריט בודד:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

תהליך תשלום על כמה פריטים:

בשדה path מציינים את האינדקס של הפריט הספציפי שאין במלאי.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

הגבלה ברמת ההזמנה (למשל, מיקוד לא אפשרי):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

הגבלה ברמת הפריט:

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

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

כתובת חיוב:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

כתובת לאספקה:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

משתמשים בשדה path כדי לציין שדות חסרים בכתובת לחיוב.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

ב-API בארכיטקטורת REST, השגיאה הזו צריכה להיות מוחזרת עם קוד סטטוס של HTTP 401.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

ב-API בארכיטקטורת REST, השגיאה הזו צריכה להיות מוחזרת עם קוד סטטוס של HTTP 403.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

שגיאות בתשלום

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}