يقيس 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 استدعاء يوميًا.
- Basic — 1000 استدعاء يوميًا.
- Pro — 10000 استدعاء يوميًا.
- Business — 50000 استدعاء يوميًا.
3حد المعدّل لكل دقيقة حسب الخطة
فوق الحصة اليومية، يُحَد كل مفتاح API بعدد من الطلبات لكل دقيقة حسب مستوى خطته. هذا حد تنعيم: يمنع عميلًا واحدًا من إرسال ارتفاع ضخم في ثانية واحدة، حتى حين تكون الميزانية اليومية بعيدة عن النفاد.
منفصلًا، تنطبق سقوف واسعة لكل IP ولكل حساب عبر كامل API لإبقاء المنصة مستقرة. في الاستخدام العادي — طلبات ثابتة مُوقَّتة — لن تمسّها أبدًا؛ فهي تُطلَق فقط على الاندفاعات المُسيئة.
- Free وBasic — 60 طلبًا في الدقيقة.
- Pro — 600 طلب في الدقيقة.
- Business — 1800 طلب في الدقيقة.
- وزّع الطلبات بدل إطلاقها كلها دفعة واحدة.
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 قبل إعادة المحاولة.