حدود الاستخدام
تعرّف على نظام نقاط البيانات (DP) في KalimaLab وترويسات الاستجابة وكيفية بناء تطبيقات مرنة.
الحدود حسب الخطة
يُحتسب الاستخدام بنقاط البيانات (DP) لكل مفتاح API. تُعاد ضبط جميع الحدود عند منتصف الليل بتوقيت UTC.
| الخطة | السعر | النقاط/اليوم | النقاط/الشهر | متزامن |
|---|---|---|---|---|
| Free | $0 | 500 DP | 5,000 DP | 5 |
| Starter | $9/mo | 5,000 DP | 100,000 DP | 20 |
| Proالأكثر شعبية | $29/mo | 25,000 DP | 500,000 DP | 100 |
| Business | $99/mo | 100,000 DP | 2,000,000 DP | Unlimited |
| Enterprise | $399/mo | 500,000 DP | 10,000,000 DP | Unlimited |
تحتاج حدوداً أعلى؟ تواصل معنا على enterprise@kalimalab.com للخطط المخصصة.
ترويسات الاستجابة لحدود الطلبات
كل استجابة API تتضمن ترويسات حدود الطلبات حتى تتمكن من تتبع استخدامك في الوقت الفعلي:
| الترويسة | الوصف | مثال |
|---|---|---|
| X-RateLimit-Limit | حد النقاط اليومي الخاص بك. | 10000 |
| X-RateLimit-Remaining | النقاط المتبقية اليوم. | 9847 |
| X-RateLimit-Reset | الطابع الزمني Unix (UTC) عند إعادة ضبط الحد. | 1710374400 |
| X-RateLimit-Policy | سياسة حد الطلبات (دائماً "day"). | day |
| Retry-After | ثوانٍ للانتظار قبل إعادة المحاولة (عند 429 فقط). | 3600 |
const response = await fetch('https://api.kalimalab.com/v1/words/random', { headers: { Authorization: `Bearer ${process.env.KALIMALAB_API_KEY}` },})const remaining = response.headers.get('X-RateLimit-Remaining')const resetAt = response.headers.get('X-RateLimit-Reset')console.log(`${remaining} DP remaining today`)console.log(`Budget resets at ${new Date(Number(resetAt) * 1000).toISOString()}`)التعامل مع 429 Too Many Requests
عند تجاوز حدك اليومي، يُعيد API حالة HTTP 429 مع هذا النص في الاستجابة:
{ "data": null, "error": { "code": "ERR_RATE_LIMIT_EXCEEDED", "message": "Daily DP budget exhausted. Your budget resets at 2026-03-18T00:00:00Z.", "limit": 500, "remaining": 0, "resetAt": "2026-03-18T00:00:00Z" }, "meta": { "requestId": "req_01j9..." }}التعامل السلس مع 429 باستخدام SDK
import { KalimaLab, RateLimitError } from 'kalimalab'const client = new KalimaLab({ apiKey: process.env.KALIMALAB_API_KEY! })async function fetchWord() { try { return await client.words.random() } catch (err) { if (err instanceof RateLimitError) { const resetMs = err.resetAt.getTime() - Date.now() console.warn(`Rate limit hit. Resets in ${Math.ceil(resetMs / 1000 / 60)} minutes.`) console.warn(`Daily limit: ${err.limit} requests`) // Return cached data, queue for later, or surface to user return null } throw err }}التعامل مع 429 باستخدام fetch الأصلي
async function fetchWithRateLimitHandling(url: string) { const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.KALIMALAB_API_KEY}` }, }) if (res.status === 429) { const retryAfter = res.headers.get('Retry-After') const waitSeconds = retryAfter ? Number(retryAfter) : 3600 console.warn(`Rate limited. Try again in ${waitSeconds}s.`) return null } return res.json()}أفضل الممارسات للبقاء ضمن الحدود
استفد من ذاكرة التخزين المؤقت 0-DP
أكثر 5,000 كلمة شيوعاً تُخدَّم من ذاكرة تخزين مؤقت من جانب الخادم بـ 0 نقطة. استخدمها أولاً قبل الانتقال إلى طبقات الأسعار المرتفعة.
اختر الطبقة المناسبة
استخدم معامل ?tier= للتحكم في تكلفة النقاط: basic (1 DP) للبحث والتحقق، وenriched (8 DP) أو full (20 DP) فقط عند الحاجة الفعلية لبيانات إضافية.
أضف تأخيراً للإكمال التلقائي
عند تشغيل حقل بحث، أضف تأخيراً بمقدار 150–300ms لاستدعاءات /v1/words/autocomplete لتجنب استهلاك النقاط عند كل ضغطة مفتاح.
إعادة المحاولة التلقائية في SDK
يعيد SDK تلقائياً محاولة أخطاء 5xx وإخفاقات الشبكة بالتراجع الأسي. لا يُعيد تلقائياً محاولة 429 — هذا مقصود حتى تتمكن من تطبيق استراتيجية قائمة الانتظار الخاصة بك.
راقب استخدامك
تحقق من X-RateLimit-Remaining في الاستجابات وسجّل تحذيراً عند انخفاضك دون 10% من ميزانيتك اليومية من النقاط.
✓تحتاج نقاطاً أكثر؟