Docsحدود الاستخدام

حدود المعدل

افهم حدود معدل FreeFileTools API وكيفية التعامل معها في تطبيقك.

حدود الطبقة المجانية

الحدالقيمة
الطلبات في الساعة50
الحد الأقصى لحجم الملف لكل طلب25 MB
نافذة حد المعدلRolling 1 hour

يُطبّق حد المعدل لكل API Key. كل مفتاح له عدّاد مستقل يُعاد تعيينه على أساس ساعة متحركة.

عند تجاوز حد المعدل

عند تجاوز حد المعدل، يُرجع API استجابة 429 Too Many Requests:

json
{
  "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
HTTP/1.1 200 OK
Content-Type: image/jpeg
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42

نصائح للبقاء ضمن الحدود

1.

تحقق من الطلبات المتبقية

راقب رأس X-RateLimit-Remaining لمعرفة عدد الطلبات المتبقية لديك.

2.

طبّق التراجع الأسي

عند تلقي استجابة 429، انتظر وأعد المحاولة مع تأخيرات متزايدة بدلاً من إرسال طلبات متتالية لـ API.

3.

خزّن النتائج مؤقتًا

إذا كنت تعالج نفس الملفات بشكل متكرر، خزّن النتائج محليًا لتجنب استدعاءات API غير الضرورية.

4.

أجرِ المعالجة الدفعية بحكمة

للمعالجة الدفعية، وزّع طلباتك على مدى الوقت بدلاً من إرسالها جميعًا دفعة واحدة.

مثال: التعامل مع حدود المعدل في JavaScript

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");
}