حدود المعدل والخطط

نوعان من الحدود

لكل خطة حصة شهرية، وهي عدد الطلبات المحتسبة في كل شهر ميلادي، وحد للطلبات في الدقيقة يحمي الواجهة من الطلبات المتدفقة دفعةً واحدة. تُعاد تعيين الحصص الساعة 00:00 UTC في اليوم الأول من كل شهر.

وتختلف الخطط أيضًا في فترة التحديث، أي مدى حداثة الأسعار. الاستطلاع بوتيرة أسرع من فترة التحديث يُرجع الأسعار نفسها مجددًا ولا يفعل سوى استهلاك الحصة.

الخطط في لمحة

• Free: 100 طلب شهريًا، وتحديث يومي، و10 طلبات في الدقيقة
• Lite: 1,000 طلب شهريًا، وتحديث كل 30 دقيقة، و30 طلبًا في الدقيقة
• Standard: 10,000 طلب شهريًا، وتحديث كل 10 دقائق، و60 طلبًا في الدقيقة
• Advanced: 50,000 طلب شهريًا، وتحديث كل 60 ثانية، و120 طلبًا في الدقيقة
• Pro: 100,000 طلب شهريًا، وتحديث كل 60 ثانية، و300 طلب في الدقيقة
• Ultra: 500,000 طلب شهريًا، وتحديث كل 15 ثانية، و600 طلب في الدقيقة
• Business: 500,000 طلب شهريًا، وتحديث كل 15 ثانية، و600 طلب في الدقيقة، إضافةً إلى اتفاقية مستوى خدمة (SLA) لوقت التشغيل
• Enterprise: 1,500,000 طلب شهريًا، وتحديث كل 5 ثوانٍ، و1,200 طلب في الدقيقة

وتتوسع الميزات أيضًا مع الخطة: تتطلب أسعار الذهب حسب العيار خطة مدفوعة، وتبدأ أسعار الطلب والعرض (bid/ask) من Standard، وتنبيهات خطافات الويب من Advanced، والبث اللحظي من Pro. راجع صفحة الأسعار للاطلاع على أسعار الخطط الحالية.

ما الذي يُحتسب طلبًا

• يُحتسب كل استدعاء ناجح لنقطة نهاية بيانات طلبًا واحدًا، بغض النظر عن عدد الرموز التي يُرجعها.
• نقطتا /symbols و/usage مجانيتان ولا تُحتسبان أبدًا.
• لا تُحتسب الطلبات المرفوضة بالخطأ 104 (حد الدقيقة) أو 106 (غير متاح في خطتك) أو 107 (المصدر غير مسموح به) أو بخطأ خادم (500، 503).
• أما الطلبات التي تفشل بسبب الاستعلام نفسه فتُحتسب، ويشمل ذلك أخطاء التحقق من 201 إلى 210 والخطأ 300 (لا توجد نتائج)، لذا تحقّق من صحة التواريخ والرموز قبل إرسالها.

تتبّع استهلاكك

تُبلغ كل استجابة لطلب مُصادَق عن حصتك في الترويسات:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9876
X-RateLimit-Used: 124
X-RateLimit-Reset: 1793491200
X-RateLimit-Reset-Date: 2026-11-01T00:00:00.000Z
X-RateLimit-Plan: Standard
X-RateLimit-Minute-Limit: 60
X-RateLimit-Minute-Remaining: 59

الأرقام نفسها موجودة في الكائن rate_limit ضمن جسم JSON. reset طابع زمني بصيغة Unix، وreset_date هو اللحظة نفسها بصيغة ISO 8601، أي بداية الشهر التالي بتوقيت UTC.

التحقق من الاستهلاك دون استهلاك الحصة

استدعِ /usage من لوحات المعلومات أو أدوات المراقبة، فهي مجانية:

{
  "success": true,
  "usage": {
    "requests_made": 124,
    "requests_quota": 10000,
    "requests_remaining": 9876,
    "plan": "standard",
    "period_start": "2026-10-01T00:00:00.000Z",
    "period_end": "2026-11-01T00:00:00.000Z"
  },
  "result": { "plan": "Standard", "used": 124, "total": 10000, "remaining": 9876 },
  "rate_limit": {
    "limit": 10000,
    "remaining": 9876,
    "reset": 1793491200,
    "used": 124,
    "plan": "Standard",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

عند بلوغ أحد الحدود

يستجيب كلا الحدين بحالة HTTP 429 وجسم خطأ:

• 104 too_many_requests: طلبات كثيرة جدًا في الدقيقة الحالية. تتضمن الاستجابة ترويسة Retry-After بعدد الثواني الواجب انتظارها. خفّف الوتيرة ثم أعد المحاولة.
• 105 quota_exceeded: استُنفدت الحصة الشهرية، وستستمر الطلبات في الفشل حتى إعادة تعيين الحصة في اليوم الأول من الشهر (UTC). أما ترقية خطتك فتسري فورًا.

{
  "success": false,
  "error": {
    "code": 105,
    "type": "quota_exceeded",
    "info": "User has reached or exceeded his subscription plan's monthly API request allowance"
  }
}

البقاء ضمن حصتك

• خزّن الاستجابات مؤقتًا لمدة لا تقل عن فترة التحديث في خطتك.
• اطلب كل الرموز التي تحتاجها في استدعاء واحد بدلًا من استدعاء منفصل لكل رمز.
• الاستطلاع كل 10 دقائق يستهلك نحو 4,500 طلب شهريًا، والاستطلاع كل دقيقة يستهلك نحو 45,000 طلب. اختر الخطة التي تناسب وتيرة الاستطلاع لديك.
• في خطة Pro وما فوقها، استخدم البث اللحظي بدلًا من الاستطلاع، واستخدم تنبيهات الأسعار للتفاعل عند بلوغ العتبات.

تجد مزيدًا من النصائح في أفضل الممارسات.