حدود المعدل
افهم حدود معدل FreeFileTools API وكيفية التعامل معها في تطبيقك.
حدود الطبقة المجانية
| الحد | القيمة |
|---|---|
| الطلبات في الساعة | 50 |
| الحد الأقصى لحجم الملف لكل طلب | 25 MB |
| نافذة حد المعدل | Rolling 1 hour |
يُطبّق حد المعدل لكل API Key. كل مفتاح له عدّاد مستقل يُعاد تعيينه على أساس ساعة متحركة.
عند تجاوز حد المعدل
عند تجاوز حد المعدل، يُرجع API استجابة 429 Too Many Requests:
{
"error": "Rate limit exceeded",
"message": "You have exceeded the rate limit of 50 requests per hour. Please try again later.",
"retryAfter": 1742
}يشير حقل retryAfter إلى عدد الثواني التي يجب الانتظار قبل إرسال طلب آخر.
رؤوس استجابة حد المعدل
تتضمن كل استجابة API رؤوسًا لمساعدتك في تتبع استخدام حد المعدل:
| الرأس | الوصف |
|---|---|
X-RateLimit-Limit | الحد الأقصى لعدد الطلبات المسموح بها في الساعة (50) |
X-RateLimit-Remaining | عدد الطلبات المتبقية في النافذة الحالية |
Retry-After | الثواني للانتظار قبل إعادة المحاولة (فقط في استجابات 429) |
مثال رؤوس الاستجابة
HTTP/1.1 200 OK
Content-Type: image/jpeg
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42نصائح للبقاء ضمن الحدود
تحقق من الطلبات المتبقية
راقب رأس X-RateLimit-Remaining لمعرفة عدد الطلبات المتبقية لديك.
طبّق التراجع الأسي
عند تلقي استجابة 429، انتظر وأعد المحاولة مع تأخيرات متزايدة بدلاً من إرسال طلبات متتالية لـ API.
خزّن النتائج مؤقتًا
إذا كنت تعالج نفس الملفات بشكل متكرر، خزّن النتائج محليًا لتجنب استدعاءات API غير الضرورية.
أجرِ المعالجة الدفعية بحكمة
للمعالجة الدفعية، وزّع طلباتك على مدى الوقت بدلاً من إرسالها جميعًا دفعة واحدة.
مثال: التعامل مع حدود المعدل في JavaScript
async function apiCall(url, options, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get("Retry-After") || "60");
console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
continue;
}
return response;
}
throw new Error("Max retries exceeded");
}