حدود الطلبات
تعرّف على حدود طلبات كلمات وترويسات الاستجابة وكيفية بناء تطبيقات مرنة.
الحدود حسب الخطة
تُطبَّق حدود الطلبات لكل مفتاح API. تُعاد ضبط جميع الحدود عند منتصف الليل بتوقيت UTC.
| الخطة | السعر | الطلبات/اليوم | الطلبات/الشهر | متزامن |
|---|---|---|---|---|
| Free | $0 | 500 | 15,000 | 5 |
| Starter | $9/mo | 10,000 | 300,000 | 20 |
| Proالأكثر شعبية | $29/mo | 100,000 | 3,000,000 | 100 |
| Business | $99/mo | 1,000,000 | 30,000,000 | 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} requests remaining`)console.log(`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 request limit exceeded. Your limit resets at 2025-03-10T00:00:00Z.", "limit": 500, "remaining": 0, "resetAt": "2025-03-10T00:00:00Z" }, "meta": { "requestId": "req_01j9..." }}التعامل السلس مع 429 باستخدام SDK
import { KalimaLab, RateLimitError } from '@kalimalab/sdk'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()}أفضل الممارسات للبقاء ضمن الحدود
خزّن الاستجابات مؤقتاً
نقطة نهاية كلمة اليوم تُعيد نفس الكلمة طوال اليوم — خزّنها مؤقتاً على مستوى التطبيق. كثير من عمليات البحث عن الكلمات مستقرة أيضاً ويمكن تخزينها في Redis أو مخزن محلي.
استخدم نقاط النهاية الجماعية
نقطة نهاية /v1/validate تقبل حتى 100 كلمة لكل طلب. جمّع طلبات التحقق بدلاً من تقديم طلب واحد لكل كلمة.
أضف تأخيراً للإكمال التلقائي
عند تشغيل حقل بحث، أضف تأخيراً بمقدار 150–300ms لاستدعاءات /v1/words/autocomplete لتجنب الإطلاق عند كل ضغطة مفتاح.
إعادة المحاولة التلقائية في SDK
يعيد SDK تلقائياً محاولة أخطاء 5xx وإخفاقات الشبكة بالتراجع الأسي. لا يُعيد تلقائياً محاولة 429 — هذا مقصود حتى تتمكن من تطبيق استراتيجية قائمة الانتظار الخاصة بك.
راقب استخدامك
تحقق من X-RateLimit-Remaining في الاستجابات وسجّل تحذيراً عند انخفاضك دون 10% من حدك اليومي.
✓تحتاج طلبات أكثر؟