القسم الحالي: حدود الطلبات

حدود الطلبات

تختلف حدود استخدام واجهة API بحسب باقتك، وتشمل نوعين من الحدود: الحصة اليومية للطلبات، والحد الأقصى لعدد الطلبات خلال الدقيقة الواحدة (Burst Limit).

قد تُطبّق هذه الحدود على مستوى مفتاح API أو الحساب أو عنوان IP. وللاطلاع على ضوابط الاستخدام المسؤول، راجع شروط استخدام المطورين.

مقارنة الباقات

الباقةالحد اليومي للطلباتالحد الأقصى للطلبات في الدقيقةمفاتيح APIWebSocketWebhooks للأحداثقواعد التنبيه
Free100/day10/min1✗00
Starter5,000/day100/min3✗00
Pro50,000/day500/min10✓310
Business150,000/day1,000/min30✓1050
Enterpriseحسب العقدحسب العقدحسب العقد✓حسب العقدحسب العقد

الحصة اليومية للطلبات

تُحتسب الحصة اليومية على مستوى الحساب، وتُشارك بين جميع مفاتيح API التابعة له، بما في ذلك مفاتيح الاستخدام الفعلي (Live) ومفاتيح الاختبار (Test). ولا يؤدي استبدال مفتاح API أو إلغاؤه إلى تجديد الحصة اليومية أو إنشاء حصة إضافية.

حدود الطلبات في الدقيقة: لمنع إساءة الاستخدام والحفاظ على استقرار الخدمة، تُطبّق حدود عدد الطلبات في الدقيقة على مستوى مفتاح API والحساب معاً. عند تجاوز هذه الحدود، تُعاد استجابة برمز HTTP 429. تُجدّد الحصص اليومية عند منتصف الليل بتوقيت الرياض (Asia/Riyadh، ‏UTC+3). أما حدود باقة Enterprise فتُحدد وفقاً للعقد، وقد تشمل حصصاً شهرية أو حدوداً مرتبطة بالموارد المستخدمة.

ترويسات حدود الطلبات

تتضمن معظم الاستجابات الناجحة لمسارات /api/v1/* الترويسات التالية:

الترويسةالوصف
X-RateLimit-Limitالحد المسموح به للطلبات
X-RateLimit-Remainingعدد الطلبات المتبقية وفقاً لطريقة احتساب الترويسة الحالية
X-RateLimit-Resetوقت تجديد الحصة اليومية، بصيغة Unix Timestamp

يشير X-RateLimit-Reset إلى منتصف الليل التالي بتوقيت الرياض (Asia/Riyadh). رغم أن الحصة اليومية تُطبّق على الحساب بالكامل وتشمل جميع مفاتيح API، فإن قيمة X-RateLimit-Remaining تُحسب حالياً بناءً على المفتاح المستخدم في الطلب. لذلك، عند استخدام عدة مفاتيح، قد تعرض الترويسة عدداً من الطلبات المتبقية أكبر من الرصيد الفعلي المتاح للحساب.

قد تحذف بعض الخوادم الوسيطة (Proxy Servers) ترويسات حدود الطلبات من الاستجابة. عند تلقي استجابة برمز HTTP 429، تكون قيمة error.code هي RATE_LIMITED، سواء كان السبب تجاوز حدود الطلبات في الدقيقة على مستوى الخوادم الطرفية أو تجاوز حصة التطبيق أو أحد حدود استخدامه. وقد تتضمن أخطاء حدود التطبيق أيضاً الحقل detail في المستوى الأعلى من الاستجابة، لتوضيح سبب الخطأ. عند توفر الترويسة Retry-After، التزم بمدة الانتظار المحددة فيها قبل إعادة المحاولة.

آخر تحديث في