حدود معدل الطلبات والحصص

نوعان من الحدود يُبقيان واجهة API سريعة للجميع:

• حد معدل الطلبات للمفتاح: كم طلبًا في الثانية يمكنه أن يرسل، مع هامش ذروة للارتفاعات القصيرة.
• حصص المؤسسة: كم طلبًا يمكن لكل مفاتيحها معًا أن ترسل في الدقيقة وفي اليوم وفي الشهر.

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

حد معدل المفتاح

يحصل كل مفتاح على معدل ثابت وهامش ذروة. يتيح لك هامش الذروة إرسال هذا العدد من الطلبات في آن واحد، وبعده تُقبل الطلبات بالمعدل الثابت.

تأتي الفئة من خطة المؤسسة. وتعرض العملية GET /v1/me فئة المفتاح الذي يستدعيها ومعدله وهامش ذروته (rate_limit). ويسري الحد على المفتاح ككل، مهما كان عدد خوادم API التي تخدم طلباتك.

نقاط النهاية المتدفقة، POST /v1/chat (مع "stream": true أو بدونه) وGET /v1/jobs/stream، خارج حد معدل المفتاح: فهي لا تستهلكه، ولا يوجد في ترويساتها RateLimit العنصر "key". لكنها تُحتسب ضمن حصص المؤسسة، مرة واحدة لكل طلب، عند بدايته. وللأسئلة حدودها الخاصة، الموصوفة أدناه.

حصص المؤسسة

يمكن أن تحدد الخطة حصص طلبات للمؤسسة: في الدقيقة، وفي اليوم، وفي الشهر. والنوافذ الزمنية فترات تقويمية بتوقيت UTC: تبدأ الدقيقة عند الثانية :00، واليوم عند 00:00 UTC، والشهر في يومه الأول عند 00:00 UTC. ويُحتسب كل طلب بمفتاح من مفاتيح المؤسسة أو برمز OAuth من رموزها، على أي عنوان. ويُحتسب الطلب المتدفق مرة واحدة، عند بدايته، مهما طالت مدته؛ وحين تُستنفد الحصة، يُرفض بالحالة 429 مثل أي طلب آخر. والطلب المرفوض بالحالة 429 لا يُحتسب.

الترويسات

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

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

تتبع الترويستان RateLimit-Policy وRateLimit مسودة IETF بعنوان RateLimit header fields for HTTP. وكل عنصر فيهما حد واحد:

تبلّغ الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset عن أشد هذه الحدود صرامةً بصيغة أبسط، للعملاء المكتوبين قبل ظهور RateLimit. وقيمة X-RateLimit-Reset بالثواني.

عند بلوغ حد

تجيب واجهة API بالحالة 429 Too Many Requests مع الترويسة Retry-After بالثواني:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

انتظر المدة المذكورة في Retry-After ثم كرر الطلب. وكرر طلبات POST وPATCH بالترويسة Idempotency-Key نفسها. ودوال إعادة المحاولة المساعدة في الأخطاء تفعل الأمرين.

وحدود الخطة الأخرى تجيب أيضًا بالحالة 429 مع Retry-After، مثل عدد الأسئلة في اليوم (limits.questions) أو عدد الإجابات الجارية في الوقت نفسه (limits.concurrent_answers). تعامل معها بالطريقة نفسها.

البقاء تحت الحدود

• اقرأ الترويسة RateLimit وأبطئ حين تنخفض قيمة r، بدل انتظار 429.
• وزّع الأعمال الكبيرة على مدى زمني، واستخدم نقاط نهاية الدفعات حيث وُجدت: دفعة من 100 مستند هي طلب واحد.
• لا تستطلع التغييرات في حلقة متلاحقة. اشترك في خطافات الويب، أو اقرأ سجل الأحداث كل بضع ثوانٍ.
• شغّل العمليات المتوازية (workers) بمحدِّد معدل مشترك: عدة عمليات تعمل بمفتاح واحد تتقاسم حد معدل واحدًا.
• اسأل جهة اتصالك في Sursa عن فئة أعلى إذا احتاج تكاملك إلى المزيد.