يقيس Telm الـ API بطريقتين: حد معدّل لكل دقيقة (سقف اندفاع) وحصة يومية (ميزانيتك الكاملة ليوم UTC). كلاهما يتوسع مع الخطة. كل رد مقيَّس يعيد X-Quota-Limit وX-Quota-Used وX-Quota-Reset كي تعرف دائمًا ميزانيتك المتبقية، ويعيد كلا الحدين 429 مع ترويسة Retry-After عند التجاوز.
1حدّان: معدّل لكل دقيقة وحصة يومية
هناك سقفان منفصلان. حد المعدّل لكل دقيقة يقيّد كم طلبًا يمكنك إجراؤه خلال أي دقيقة واحدة، مُنعِّمًا الاندفاعات. أما الحصة اليومية فهي ميزانيتك الإجمالية: تقيّد كم استدعاءً مقيَّسًا يمكنك إجراؤه عبر كامل يوم UTC.
إنهما مستقلان. يمكنك بلوغ حد الدقيقة بينما ما زال لديك متسع كبير من الحصة اليومية (أنت ببساطة ترسل بسرعة مفرطة)، أو استنفاد حصتك اليومية بينما أنت تحت حد الدقيقة بكثير (استهلكت اليوم). كلاهما يعيد حالة 429، لكن لأسباب مختلفة — تحقّق من رمز الخطأ في الجسم لتمييزهما.
- حد المعدّل لكل دقيقة — سقف اندفاع، يُعاد ضبطه كل دقيقة.
- الحصة اليومية — إجمالي استدعاءاتك المقيَّسة لليوم، تُعاد عند منتصف الليل UTC.
- تُحسَب الحصة مرة واحدة لكل حساب، مشتركة عبر كل مفاتيحك.
2الحصة اليومية حسب الخطة
حصتك اليومية هي عدد استدعاءات API المقيَّسة التي يمكنك إجراؤها لكل يوم UTC، وتعتمد على خطتك. العدّاد مشترك عبر كل مفاتيحك ويتبع أفضل خطة بين المجموعات التي تديرها — دون اشتراك مدفوع، أنت على مستوى Free.
النافذة هي يوم تقويم UTC، فيُعاد ضبط عدّاد المُستخدَم إلى صفر عند منتصف الليل UTC. فحص بريد مزعج دُفعي يكلّف استدعاءً واحدًا لكل عنصر في الدُّفعة، لا استدعاءً واحدًا للطلب كله.
- Free — 100 استدعاء في اليوم.
- Pro — 10,000 استدعاء في اليوم.
- Business — 50,000 استدعاء في اليوم.
- لفحوصات الذكاء الاصطناعي على نقطة نهاية فحص الرسائل المزعجة الفردية حصة يومية خاصة بها — 1,000 على Pro و10,000 على Business.
3حد المعدّل لكل دقيقة حسب الخطة
إلى جانب الحصة اليومية، يُقيَّد حسابك بعدد من الطلبات في الدقيقة حسب مستوى خطته، مشترك بين كل مفاتيحك. هذا حدّ تنعيم: يمنع عميلًا واحدًا من إرسال دفقة ضخمة في ثانية واحدة، حتى لو كانت الميزانية اليومية بعيدة عن النفاد.
وبشكل منفصل، تنطبق سقوف عامة لكل عنوان IP ولكل حساب على واجهة API بأكملها للحفاظ على استقرار المنصة. في الاستخدام العادي — طلبات منتظمة ومتباعدة — لن تقترب منها أبدًا؛ فهي لا تُفعَّل إلا عند الدفقات المسيئة.
- Free — 60 طلبًا في الدقيقة.
- Pro — 600 طلب في الدقيقة.
- Business — 1,800 طلب في الدقيقة.
- وزّع الطلبات على فترات بدل إطلاقها كلها دفعة واحدة.
4قراءة ميزانيتك المتبقية
لن تضطر أبدًا للتخمين كم بقي من الحصة. كل رد مقيَّس — نجاح أو فشل — يضم ثلاث ترويسات: X-Quota-Limit (حدك اليومي)، وX-Quota-Used (كم استدعاءً أنفقت اليوم)، وX-Quota-Reset (اللحظة، بتوقيت UTC، حين يُعاد ضبط العدّاد).
تردّد إندبوينتات فحص البريد المزعج أيضًا الأرقام نفسها داخل جسم الرد ضمن كائن quota، كي تقرأ ميزانيتك المتبقية دون تحليل الترويسات. استخدمها لتوقيت طلباتك ولتحذير نفسك قبل أن تنفد.
- X-Quota-Limit — حد استدعاءاتك اليومي.
- X-Quota-Used — الاستدعاءات المُنفَقة حتى الآن اليوم.
- X-Quota-Reset — وقت الإعادة بتوقيت UTC (RFC 3339).
- ردود فحص البريد المزعج تضم أيضًا كائن quota بالحقول نفسها.
5ماذا يحدث عند 429
حين تتجاوز أيًا من الحدين، يعيد API حالة HTTP 429 مع ترويسة Retry-After تخبرك كم ثانية تنتظر. لحد المعدّل لكل دقيقة، Retry-After نحو دقيقة. أما للحصة اليومية، فيحمل الجسم رمز daily_quota_exceeded مع خطتك وحدك وعدد المُستخدَم ووقت الإعادة وتلميح ترقية، وتَعُدّ Retry-After تنازليًا حتى منتصف الليل UTC.
الطريقة الصحيحة للتعامل مع 429 هي التراجع وإعادة المحاولة بعد تأخير Retry-After، لا قصف الإندبوينت. العملاء حسنو السلوك يقرؤون الترويسة ويتوقفون؛ أما العملاء الذين يعيدون المحاولة فورًا فيبقون محجوبين فحسب.
- 429 rate_limit_exceeded — أرسلت بسرعة مفرطة؛ انتظر نحو دقيقة.
- 429 daily_quota_exceeded — استُهلِك اليوم؛ انتظر حتى إعادة UTC أو رقِّ.
- احترم دائمًا ترويسة Retry-After قبل إعادة المحاولة.