حدود معدل الطلبات

يمر كل request لـ FourA API عبر rate limiting. ستواجه نوعين من الحدود: concurrency (الطلبات المتزامنة) و RPM (الطلبات لكل دقيقة). يتم فرض كلاهما لكل خدمة.

كيف تعمل حدود معدل الطلبات

يفرض API الحدود على مستويين:

حد API العام: ينطبق على جميع requests بغض النظر عن endpoint. يتم تشغيل هذا الفحص أولاً.
الحد الخاص بالخدمة: ينطبق بشكل منفصل على كل endpoint (single، أو proxy، أو browser). يتم تشغيل هذا الفحص فقط في حال تجاوز الحد العام.

إذا تم الوصول إلى الحد العام، فلن يتم تشغيل الفحص الخاص بالخدمة. يجب أن يجتاز request كلا الفحصين قبل أن يصل إلى backend.

يتتبع كل مستوى مقياسين:

Concurrency: عدد requests التي تعمل في نفس الوقت.
RPM: عدد requests التي أرسلتها في آخر 60 ثانية.

استجابات rate limit

عندما تصل إلى الحد الأقصى، يعيد API استجابة JSON تحتوي على استخدامك الحالي والحدود المعمول بها.

429: تجاوز حد RPM

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

لقد أرسلت عددًا كبيرًا جدًا من requests في الدقيقة الأخيرة. انتظر فترة retryAfter قبل إرسال المزيد.

503: تجاوز حد Concurrency

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

هناك عدد كبير جدًا من requests التي تعمل في نفس الوقت. بعض requests السابقة لم تنتهِ بعد.

الخدمة معطلة

عندما يتم إيقاف تشغيل الخدمة مؤقتًا للصيانة، يعيد API رمز الحالة 503 مع رسالة خطأ مختلفة:

{
  "error": "Service disabled",
  "status": 503,
  "retryAfter": 60
}

هذا ليس rate limit. الخدمة غير متاحة مؤقتًا. تحقق من قيمة retryAfter وأعد المحاولة بعد هذا العدد من الثواني. يتم حل هذا عادةً في غضون دقائق.

لا تخلط بين هذا وبين استجابة 503 الخاصة بـ concurrency. لن تتضمن استجابة "Service disabled" الحقول current أو limits.

حقول الاستجابة

الحقل	النوع	الوصف
`error`	string	رسالة خطأ مقروءة للمستخدم
`status`	number	رمز حالة HTTP (429 أو 503)
`service`	string	الخدمة التي وصلت إلى الحد الأقصى: single، أو proxy، أو browser، أو api
`retryAfter`	number	وقت الانتظار الموصى به بالثواني قبل إعادة المحاولة
`current.concurrency`	number	عدد requests النشطة حاليًا لديك
`current.rpm`	number	عدد requests الخاصة بك في آخر 60 ثانية
`limits.maxConcurrency`	number	الحد الأقصى المسموح به لـ requests المتزامنة
`limits.maxRpm`	number	الحد الأقصى المسموح به لـ requests في الدقيقة

التعامل مع rate limits

استخدم الحقل retryAfter لتطبيق التراجع التدريجي (backoff):

import requests
import time

def fetch(url, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={
                "X-API-Key": "YOUR_API_KEY",
                "Content-Type": "application/json"
            },
            json={"method": "GET", "url": url}
        )

        if resp.status_code in (429, 503):
            data = resp.json()
            wait = data.get("retryAfter", 5)
            time.sleep(wait)
            continue

        return resp

    raise Exception("Max retries exceeded")

نصائح

تحقق من حقول current في استجابات rate limit لفهم أنماط استخدامك.
إذا كنت تصل باستمرار إلى حدود concurrency، فقلل عدد requests المتوازية.
إذا كنت تصل إلى حدود RPM، فأضف تأخيرًا بسيطًا بين requests أو قم بتجميعها على مدى فترة زمنية أطول.
تختلف قيمة retryAfter حسب نوع الحد: ثانيتان لـ concurrency، و 5 ثوانٍ لـ RPM.
تعني استجابة "Service disabled" أن هناك صيانة قيد التنفيذ. لا تستمر في إرسال requests بشكل متكرر إلى endpoint.