رموز الخطأ

توضّح هذه الصفحة رموز الخطأ الأساسية التي يجب عرضها في ردود واجهة برمجة التطبيقات عند التكامل مع Google باستخدام بروتوكول Universal Commerce Protocol (UCP). تضمن رموز الخطأ المتسقة التواصل الواضح وتساعد Google في التعامل مع السيناريوهات المختلفة بشكل مناسب.

عند حدوث خطأ في النشاط التجاري، يجب أن تعرض واجهة برمجة التطبيقات رسالة استجابة تتضمّن رمز الحالة 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: يشير إلى أنّه تعذّر إكمال العملية المطلوبة. من المحتمل أنّ على المنصة أو المستخدم اتّخاذ إجراء وإعادة المحاولة. يُرجى الاطّلاع على مواصفات message-error.
  • يتم تحديد طبيعة الخطأ النهائية من خلال الحقل severity (unrecoverable أو recoverable)، وليس الخطأ code.
• warning: يشير إلى أنّه لم يتم حظر العملية، ولكن هناك شيء جدير بالملاحظة يجب إبلاغ المستخدم به. لن يؤدي ذلك إلى إيقاف العملية، بل سيوفر سياقًا مهمًا. راجِع مواصفات رسائل التحذير.

مرجع رمز الخطأ

أمثلة على رموز الخطأ

يقدّم هذا القسم أمثلة على 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

في واجهة REST API، يجب عرض هذا الخطأ مع رمز حالة HTTP 401.

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

insufficient_scope

في واجهة REST API، يجب عرض هذا الخطأ مع رمز حالة 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."
}