رمز سبب ثابت
يُستخدم رمز خطأ ثابت في منطق العميل والتقارير والتوزيع التلقائي للطلبات.
الوثائق / أخطاء API
معالجة أخطاء API
مخطط موحد للاستجابات ورموز الأخطاء والأعطال المؤقتة والنتائج غير المعروفة والتشخيص والاستعادة الآمنة لتكاملات iGaming.
HTTP
نتيجة الطلب
الرموز
سبب واضح
إعادة المحاولة
إجراء آمن
البحث
تشخيص الطلب
دورة معالجة الخطأ
من استجابة API إلى الاستعادة
01
تحديد نوع النتيجة
تحقق من حالة HTTP ورمز السبب وفئة الخطأ وحالة العملية.
02
حفظ بيانات التحليل
سجل معرفات الطلب والعملية ومسار الطريقة والوقت ومرجع المزود والمعلمات الآمنة.
03
اختيار إجراء آمن
صحح البيانات أو أوقف العملية أو أعد الطلب بعد تأخير أو تحقق من الحالة الحالية.
04
الاستعادة والمراقبة
امنع التكرار ونفذ التسوية وأبلغ المسؤولين وأغلق سبب العطل.
نظرة عامة
يجب أن يوضح الخطأ السبب والإجراء التالي
لا تكفي استجابة HTTP 400 أو 500 وحدها. يعيد API موثوق رمز سبب ثابتًا ويربط الاستجابة بمعرف الطلب ويسمح بفهم ما إذا كان يلزم تصحيح البيانات أو إيقاف العملية أو إعادة الطلب أو التحقق من حالتها بشكل منفصل.
إجراء متوقع
توضح فئة الخطأ ما إذا كان يمكن إعادة الطلب وما البيانات التي يجب تغييرها.
ربط للتشخيص
تربط معرفات الطلب والعملية والمزود سجلات العميل بالأنظمة الداخلية والدعم.
بنية الخطأ
بنية موصى بها لاستجابة الخطأ
يجب أن تكون الاستجابة موجزة وثابتة وقابلة للمعالجة الآلية دون كشف تفاصيل التنفيذ الداخلية أو البيانات الحساسة.
رمز الخطأ
معرف ثابت للسبب لا يتغير عند تحرير الرسالة التوضيحية.
الوصف
توضيح قصير وآمن دون كود داخلي أو استعلامات قاعدة بيانات أو أسرار أو تفاصيل غير ضرورية.
معرف الطلب
معرف فريد للعثور على العملية في السجلات والتواصل مع الدعم.
بيانات إضافية
حالة مسموحة أو حد أو حالة حالية أو سبب رفض آمن.
يمكن إعادة المحاولة
مؤشر صريح على خطأ مؤقت لا يلغي حماية العملية من التنفيذ المكرر.
فترة الانتظار قبل إعادة المحاولة
تأخير موصى به بالثواني أو ترويسة HTTP لحدود الطلبات وعدم التوفر المؤقت.
أخطاء الحقول
قائمة بالحقول التي بها مشكلات مع رمز السبب ومسار القيمة وتوضيح آمن.
رابط الوثائق
رابط ثابت أو معرف قسم يوضح السبب وطريقة الإصلاح.
فئات الأخطاء
فئات الأخطاء الرئيسية
توضح حالة HTTP الفئة العامة للنتيجة، بينما يحدد الرمز الداخلي السبب المحدد والإجراء المسموح.
خطأ في بيانات الإدخال
صيغة غير صحيحة أو حقل إلزامي مفقود أو قيمة غير مدعومة أو دقة مبلغ غير صحيحة أو بنية طلب مخالفة.
خطأ في المصادقة
رمز مميز أو مفتاح API أو توقيع أو وقت طلب أو معرف أحادي الاستخدام مفقود أو منتهي الصلاحية أو غير صحيح.
صلاحيات غير كافية
تم التعرف على العميل لكنه لا يملك الدور أو العلامة التجارية أو السوق أو الإذن المطلوب للإجراء.
الكائن غير موجود
اللاعب أو الدفع أو الجولة أو تحقق KYC أو المزود أو كائن آخر غير موجود أو غير متاح للعميل.
تعارض الحالة
تغير إصدار الكائن أو حالته، أو سبق استخدام معرف العملية بمعلمات مختلفة.
مخالفة قاعدة عمل
رصيد غير كافٍ أو تجاوز حد أو لاعب محظور أو سوق ممنوع أو انتقال حالة غير مسموح.
عدد كبير جدًا من الطلبات
تم تجاوز العدد المسموح من الطلبات للعميل أو الطريقة أو الدور أو العملية الحرجة.
المزود غير متاح
الخدمة الخارجية غير متاحة أو تستجيب بتأخير أو لا تقبل العمليات مؤقتًا.
خطأ داخلي
خطأ غير متوقع في المنصة دون كشف تفاصيل داخلية، مع معرف للتشخيص.
إعادة المحاولة والاستعادة
إعادة الطلب ونتيجة غير معروفة
تكون إعادة المحاولة آمنة فقط بعد تحديد نوع الخطأ والتحقق مما إذا كانت العملية الأصلية قد نُفذت بالفعل.
01
تحقق مما إذا كانت إعادة المحاولة مسموحة
أخطاء البيانات والصلاحيات وقواعد الأعمال تتطلب عادةً تصحيح الطلب بدلًا من إعادة إرساله.
02
الاحتفاظ بمفتاح العملية نفسه
يجب ألا تؤدي إعادة عملية مالية أو لعب أو عملية حرجة أخرى إلى إنشاء نتيجة جديدة.
03
زيادة الفاصل بين المحاولات
تزداد الفواصل تدريجيًا، وتراعي الوقت الذي يحدده الخادم، وتحد العدد الإجمالي للمحاولات.
04
التوقف والإحالة للمراجعة
بعد استنفاد المحاولات، تُسجل العملية كغير مكتملة وتُحال إلى مراجعة يدوية أو تسوية.
عدم وجود استجابة لا يعني رفض العملية
عند انقطاع الاتصال بعد إرسال الطلب، قد تبقى النتيجة غير معروفة. قبل إعادة المحاولة يجب التحقق من الحالة باستخدام معرف العملية أو انتظار إشعار موثوق.
التشخيص والمراقبة
السجلات والمعرفات والمؤشرات والإشعارات
يجب أن يعيد التشخيص مسار الطلب بين المنصة والمحول والمزود الخارجي دون تخزين بيانات حساسة غير ضرورية.
سياق التحليل
معرفات الطلب والارتباط والعملية والمزود الخارجي.
مسار الطريقة وطريقة طلب HTTP والبيئة والعميل والوقت ومدة الاستجابة.
حالة HTTP ورمز الخطأ وعدد المحاولات والحالة النهائية.
الحقول الحساسة المخفية والترويسات الآمنة ونتيجة التحقق من التوقيع.
المراقبة والإشعارات
نسبة الأخطاء حسب الطريقة والمزود والعميل وفئة السبب.
زيادة الاستجابات البطيئة وأخطاء HTTP 5xx والتوقيعات غير الصحيحة وحدود المعدل.
عدد إعادة المحاولات والعمليات ذات النتيجة غير المعروفة ومهام الاستعادة.
إشعارات بحدود ومسؤولين وقواعد تصعيد المشكلة.
الاختبار
ما يجب اختباره في بيئة الاختبار
يجب أن تعيد بيئة الاختبار إنتاج كل فئة خطأ مهمة وتؤكد السلوك الصحيح للعميل وإعادة المحاولات والمراقبة.
أخطاء بيانات الإدخال
حقول مفقودة وأنواع غير صحيحة وقيم غير مدعومة ودقة المبلغ وعدة أخطاء في الوقت نفسه.
الوصول والصلاحيات
مفتاح غير صحيح أو رمز منتهي الصلاحية أو توقيع خاطئ أو دور غير مصرح أو IP محظور أو معرف أحادي الاستخدام مكرر.
لا توجد استجابة والنتيجة غير معروفة
انقطاع الاتصال قبل الإرسال وبعد قبول العملية وأثناء استلام الاستجابة النهائية.
تحديد المعدل
HTTP 429 وفترة الانتظار الموصى بها والطلبات المتوازية والاستعادة بعد انتهاء التقييد.
أخطاء المزود
عدم التوفر أو الصيانة أو استجابة غير صحيحة أو إشعار متأخر أو حالة متناقضة.
إعادة المحاولة والإيقاف الوقائي
تحديد عدد المحاولات وزيادة فترات الانتظار وإيقاف الطلبات مؤقتًا والاستعادة المضبوطة والإحالة اليدوية للمشكلة.
قائمة تحقق قبل الإطلاق
يُطلق التكامل الفعلي بعد التحقق من بنية الأخطاء وسلوك العميل والحماية من التكرار والتشخيص.
تعيد جميع الأخطاء رمز سبب ثابتًا ومعرف طلب.
تفاصيل الأخطاء لا تكشف الأسرار أو التنفيذ الداخلي.
فئات الأخطاء المؤقتة والدائمة موثقة.
تستخدم إعادة العملية الحرجة مفتاح الحماية من التكرار نفسه.
تُعالج النتيجة غير المعروفة عبر التحقق من الحالة أو إشعار موثوق.
تم إعداد السجلات والمؤشرات والإشعارات وطابور الاستعادة وقواعد تصعيد المشكلة.
هل تحتاج إلى توحيد أخطاء API؟
أرسل استجابات HTTP الحالية ورموز الأخطاء وقواعد إعادة المحاولة والسيناريوهات الإشكالية. سيساعد APIACE في تحديد نموذج أخطاء موحد واستعادة آمنة ومراقبة.