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

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

نظرة عامة

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

ملاحظة: يتم طرح بنية استجابة الخطأ هذه تدريجيًا في جميع أنحاء Merchant API. تتّبع الأخطاء التي تعرضها واجهات برمجة التطبيقات الفرعية الخاصة بالمنتجات والتقارير ومصادر البيانات التنسيق الموضّح هنا فقط. قد تظل الأخطاء الواردة من واجهات برمجة التطبيقات الفرعية الأخرى بتنسيق قديم وقد لا تتضمّن ErrorInfoالبيانات الوصفية

.

بنية استجابة الخطأ

استجابة الخطأ هي كائن 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: تكون هذه الأخطاء عادةً مؤقتة. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. ملاحظة: إذا استمرّت حالة internal_error بعد عدّة محاولات إعادة مع التراجع، يُرجى الاطّلاع على كيفية التواصل مع فريق دعم Merchant API.

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

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

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