حدود المعدل

تُحدَّد واجهة المطورين بالمعدل لكل organization، لكل دقيقة، مع تحديد الميزانية بحسب خطتك. تخبرك كل استجابة مُصادَق عليها بـ key بموقعك بالضبط، لتتمكن من ضبط حركتك قبل بلوغ الحد.

ترويسات حد المعدل

تحمل كل استجابة مُصادَق عليها بـ key ثلاث ترويسات:

النافذة هي نافذة منزلقة مدتها 60 ثانية — تُعبَّر ميزانية كل خطة لكل دقيقة. اقرأ RateLimit-Remaining وأبطئ كلما اقترب من الصفر.

HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 41
Content-Type: application/json

عند تجاوزك للحد

يُرجع طلب يتجاوز الميزانية الرمز 429 مع غلاف الخطأ القياسي وترويسة Retry-After تخبرك بعدد الثواني التي يجب الانتظار:

HTTP/1.1 429 Too Many Requests
Retry-After: 41
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 41
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your plan's request allowance."
  }
}

التعامل مع 429

• احترم Retry-After — انتظر العدد المُشار إليه من الثواني قبل إعادة المحاولة.
• تراجع أُسّيًا إذا استمررت في تلقّي 429.
• استخدم RateLimit-Remaining بشكل استباقي لتقييد الدفعات قبل رفضها.

الفشل المفتوح

صُمِّم محدِّد المعدل لـ يفشل مفتوحًا: إذا كان المحدِّد نفسه غير متاح، تمرّ الطلبات بدلًا من حظرها. لا ينبغي أن ترى أبدًا حالات 429 زائفة بسبب توقف المحدِّد — لكن لا ينبغي أيضًا أن تعتمد على المحدِّد لفرض الصحة في عميلك الخاص. اضبط حركتك باستخدام ترويسات RateLimit-*.

حصة الاستعلام

يُقاس تشغيل agent (POST /agents/{id}/query) إضافيًا مقابل حصة استعلام خطتك من جهة الخادم. تجاوزها يُرجع 429 على المسار الحاجب، أو حدث error واحد على مسار التدفق. راجع صفحة استعلام Agent للتفاصيل.