الحدود والحصص

تنطبق ميزانيتان على كل طلب يُرسَل بمفتاح: حدّ المعدل (عدد الطلبات في الدقيقة، مع دفعة قصيرة مسموح بها) والحصة اليومية للمؤسسة (حسب خطتها). وتتقاسم الطلبات المجهولة حدّ معدل واحدًا لكل عنوان عميل.

حدود المعدل

عند بلوغ الحد تجيب الواجهة البرمجية بـ 429 مع Retry-After (بالثواني) والرمز rate_limited. انتظر تلك المدة، ثم تابع. وأضف تفاوتًا عشوائيًا (jitter) إذا كان عدة عمّال يتقاسمون مفتاحًا واحدًا.

الحصص اليومية

تتقاسم مفاتيح المؤسسة ورموز OAuth الخاصة بها حصة يومية واحدة تحددها خطتها (10,000 طلب يوميًا في الخطة المجانية). تتجدد الحصة بالتساوي على مدار اليوم. وعندما تنفد، تتلقى الطلبات 429 مع الرمز quota_exceeded وRetry-After.

الاستخدام

تُحصى الطلبات لكل مفتاح ولكل يوم. يجمع GET /v1/orgs/{org_id}/api-usage?month=YYYY-MM طلبات شهر كامل لكل مفتاح ولكل عميل OAuth (تُحصى رموزه الصالحة لساعة واحدة معًا)، إلى جانب الحصة اليومية؛ ويعطي GET /v1/orgs/{org_id}/api-keys/{key_id}/usage أيام مفتاح واحد. وتُبنى فواتير استخدام الواجهة البرمجية، حين تسعّره الخطة، من الأعداد نفسها.

كيف تكون عميلًا جيدًا

• خزّن ما تقرؤه مؤقتًا. صفحات الشركات تتغير ببطء؛ ويبيّن Cache-Control المدة التي تبقى فيها الإجابة العامة حديثة.
• فضّل خطافات الويب على الاستعلام الدوري لمعرفة أحداث مؤسستك.
• أعِد محاولة 429 و5xx مع تباعد متزايد بين المحاولات؛ ولا تُعِد محاولة رموز 4xx الأخرى دون تغيير الطلب.