التعامل مع ردود الأخطاء

يوضّح هذا الدليل كيفية التعامل مع الأخطاء التي تعرضها Merchant API. إنّ فهم بنية استجابة الخطأ وثباتها أمر بالغ الأهمية لإنشاء عمليات دمج قوية يمكنها التعافي تلقائيًا من حالات الفشل أو تقديم ملاحظات مفيدة للمستخدمين.

نظرة عامة

عندما يتعذّر تنفيذ طلب بيانات من واجهة برمجة التطبيقات Merchant API، تعرض واجهة برمجة التطبيقات رمز حالة HTTP عاديًا (4xx أو 5xx) ونص استجابة JSON يتضمّن تفاصيل حول الخطأ. تتّبع Merchant API معيار AIP-193 لتفاصيل الأخطاء، ما يوفّر معلومات قابلة للقراءة آليًا تتيح لتطبيقك التعامل مع سيناريوهات أخطاء معيّنة آليًا.

بنية ردّ الخطأ

استجابة الخطأ هي كائن JSON يحتوي على حقول عادية، مثل code وmessage وstatus، كما يتضمّن مصفوفة details. للتعامل مع الأخطاء آليًا، عليك البحث عن كائن ضمن details حيث تكون قيمة @type هي type.googleapis.com/google.rpc.ErrorInfo.

يوفّر عنصر ErrorInfo هذا بيانات منظَّمة وثابتة حول الخطأ:

• النطاق: يشير إلى المجموعة المنطقية للخطأ، وعادةً ما يكون 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: المفاتيح ضِمن خريطة البيانات الوصفية (مثل 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.

تنفيذ خوارزمية الرقود الأسي الثنائي

بالنسبة إلى الأخطاء التي تشير إلى عدم التوفّر مؤقتًا أو الحدّ من معدّل الطلبات، عليك تنفيذ استراتيجية رقود أسي ثنائي، أي الانتظار لفترة قصيرة قبل إعادة المحاولة، وزيادة وقت الانتظار مع كل تعذّر لاحق.

• quota/request_rate_too_high: يشير هذا الخطأ إلى أنّك تجاوزت حصتك في الدقيقة لمجموعة حصص معيّنة، لذا عليك خفض معدّل طلباتك.
• ‫internal_error: تكون هذه الأخطاء عادةً مؤقتة، لذا يُرجى إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.

كيفية التواصل مع فريق دعم Merchant API

إذا كنت بحاجة إلى التواصل مع فريق دعم Merchant API بشأن خطأ معيّن، يُرجى تقديم المعلومات التالية في طلبك:

1. ردّ الخطأ المحدّد الذي تم تلقّيه
2. اسم طريقة واجهة برمجة التطبيقات
3. حمولة الطلب
4. الطوابع الزمنية أو النطاق الزمني الذي تم خلاله استدعاء الطريقة وتلقّي الأخطاء