الانتقال إلى المحتوى الرئيسي
يطبّق Didit عدة طبقات من تحديد المعدل للحفاظ على استقرار واجهة API مع السماح بدفعات معتادة من حركة المرور. تُطبَّق الحدود لكل معرّف، وهو مفتاح x-api-key الخاص بك، أو عنوان IP لعميلك إذا لم يُرسَل مفتاح API. يحتفظ كل نطاق بعدّاد مستقل بنافذة منزلقة مدتها 60 ثانية.

المعرّف والاستثناءات

يختار الوسيط معرّف تحديد المعدل بهذا الترتيب:
  1. ترويسة x-api-key: عدّاد على مستوى المفتاح.
  2. أول قفزة في X-Forwarded-For: عدّاد على مستوى عنوان IP.
  3. REMOTE_ADDR: عدّاد على مستوى عنوان IP.
تتجاوز الاستدعاءات التالية تحديد المعدل بالكامل:
  • مفتاح DIDIT_WEBAPP_API_KEY الداخلي (يُستخدم فقط بواسطة وحدة تحكم Didit).
  • endpoints المحمية بالإذن IsValidSession (حركة الجلسات المضمّنة/SDK).
  • GET /system/healthcheck (يخدمه HealthMiddleware قبل هذه المجموعة من الوسطاء).
  • webhooks المزوّدين: Stripe، وفحص AML، وردود استدعاء التحقق من الوجه، وتعديل قوائم KYC.

الحدود العامة

تُصنَّف كل طلب موثّق أيضاً حسب طريقة HTTP ضمن نطاق عام، بحيث يرث أي مسار جديد حداً افتراضياً معقولاً: تُحتسب عمليات إنشاء المعاملات وإدخال الأحداث ضمن ingest-write بدلاً من generic-write: يحصل تكامل الإدخال عالي الحجم على 600 طلب في الدقيقة لكل مفتاح API دون استنفاد ميزانية عمليات الكتابة الأخرى. تُطبَّق حدود endpoint (في القسم التالي) بالإضافة إلى الحد العام. أول نطاق يتجاوز عدّاده هو الذي يعيد 429.

حدود endpoint

يعرّف الوسيط نطاقات أكثر صرامة للمسارات الأعلى تأثيراً:
تخدم SessionV3RetrieveView المسار GET /v3/session/<id>/decision/ ولا يندرج ضمن نطاق session-decision. يخضع فقط للسقف العام generic-get البالغ 600 في الدقيقة. ينطبق حد معدل القرار البالغ 100 في الدقيقة على مسارات القرار في الإصدارين v1 وv2.
يعرّف الكود أيضاً FREE_SESSION_RATE_LIMIT = 10 وPAID_SESSION_RATE_LIMIT = 600. هذه الثوابت غير مطبّقة حالياً على POST /v3/session/، إذ يستخدم هذا endpoint حد session-v2-create الواحد البالغ 600 في الدقيقة لكل تطبيق. لا تبنِ تخطيط السعة على حد معدل للمستوى المجاني لكل سير عمل حتى يُوثَّق بوصفه فعّالاً.

شكل استجابة 429

عند تجاوز أي نطاق تحصل على استجابة HTTP 429 بهذا الجسم وهذه الترويسات:
تظهر ترويسات X-RateLimit-* فقط في استجابة 429، ولا تتضمنها الاستجابات الناجحة حالياً. استخدم قيمة Retry-After (أو X-RateLimit-Reset - now) مدةً للانتظار قبل المحاولة التالية.

إرشادات للعميل البرمجي

  • احترم Retry-After كحدٍّ أدنى لفترة التراجع. وفوقه، طبّق التراجع الأُسّي مع الجِتر (5s → 10s → 20s → 40s ± random) حتى لا يتزامن العميلان اللذان يتلقيان 429 في اللحظة نفسها.
  • توقّف عن إعادة المحاولة بعد حدٍّ أقصى صغير (مثلاً 5 محاولات). اعرض الخطأ على المستدعي وأبلغ فريقك، فتكرار 429 لفترة طويلة يدل عادةً على حلقة تكرار خارجة عن السيطرة، لا على ارتفاع عابر في الحركة.
  • استخدم معرّفاً واحداً لكل حمل عمل. مشاركة x-api-key بين عدة خوادم خلفية تجمعها في العداد نفسه، وقد يؤدي ذلك إلى أن يستهلك أحدها الحصة فيحرم البقية. أصدر تطبيقاً منفصلاً (وبالتالي api_key منفصلاً) لكل بيئة أو علامة تجارية أو عميل. راجع التسجيل البرمجي.
  • خزّن نتائج قراءات القرار مؤقتاً. نقاط النهاية /decision/ غير مصممة لحلقات الاستطلاع المتقاربة زمنيًا. إذا كنت تحتاج إلى تحديثات فورية، فاستخدم webhook ولا تستدعِ GET /v3/session/<id>/decision/ إلا لاستكمال البيانات المفقودة أو للتدقيق.
  • أنشئ ملفات PDF دون اتصال. عرض ملفات PDF يستهلك موارد المعالج، والحد الأقصى هو 50 في الدقيقة. شغّله من قائمة انتظار بعد أن تصل الجلسة إلى حالة نهائية، لا عند كل عرض للصفحة.

مثال على عميل يراعي استجابات 429

هل تحتاج إلى سعة أكبر؟

إذا كان 600 جلسة في الدقيقة غير كافٍ، كأن تكون بصدد حملة تسويقية أو استكمال بيانات، فراسل support@didit.me مع معرّف application الخاص بك (UUID) ومعدلات الاستخدام المستمرة والمتوقعة ومعدلات الاندفاع المتوقعة. تُضبط التجاوزات لكل تطبيق على حدة.
آخر تعديل في ٧ نوفمبر ٢٠٢٦