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

يوضّح هذا الدليل كيفية التعامل مع الأخطاء التي تعرضها 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 هذا بيانات منظَّمة وثابتة حول الخطأ:

• domain: التجميع المنطقي للخطأ، وعادةً ما يكون merchantapi.googleapis.com.
• metadata: خريطة للقيم الديناميكية المرتبطة بالخطأ. ويشمل ذلك ما يلي:
  • REASON: معرّف محدّد وثابت للخطأ الدقيق (مثل INVALID_NAME_PART_NOT_NUMBER، PERMISSION_DENIED_ACCOUNTS). هذا الحقل موجود دائمًا. استخدِم هذا الحقل لمعالجة الأخطاء بدقة في منطق تطبيقك.
  • HELP_CENTER_LINK: يوفّر سياقًا وتعليمات إضافية لحلّ المشكلة. لا يظهر هذا الحقل لجميع الأخطاء، ولكنّنا نخطّط لتوسيع نطاقه بمرور الوقت للأخطاء التي قد تحتاج إلى مزيد من السياق.
  • Other dynamic fields: مفاتيح أخرى توفّر سياقًا، مثل اسم الحقل غير الصالح (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 support بشأن خطأ معيّن، قدِّم المعلومات التالية في طلبك:

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