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

يوضّح هذا الدليل كيفية التعامل مع الأخطاء التي تعرضها 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: تكون هذه الأخطاء عادةً مؤقتة. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.

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

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

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