حدود المعدل (Rate Limits)
يمر كل طلب FourA API بثلاثة فحوصات قبل أن يصل إلى المحرك: حدود خطتك الخاصة، ثم الحصة المشتركة للمنصة لجميع حركات المرور، ثم الحصة المشتركة للمنصة لـ endpoint الذي طلبته. يمكن لكل فحص رفض الطلب بشكل مستقل، ويستجيب كل منها بـ body مختلف.
الفحوصات الثلاثة، بالترتيب
- حدود الخطة. ما تسمح به خطتك الخاصة: ما هي endpoints والمعلمات المضمنة فيها، وكم عدد الطلبات التي يمكن تشغيلها في وقت واحد لكل endpoint، وكم عددها في الدقيقة، وكم عدد طلبات المتصفح يوميا، بالإضافة إلى الرصيد وعرض النطاق الترددي المتاحين في دورة الفوترة.
- حد المنصة العام. كل ما يتعامل معه مضيف API الذي اتصلت به في تلك اللحظة، أيا كان endpoint الذي اتجهت إليه حركة المرور. يبلغ الرفض هنا عن
"service": "api". - حد المنصة لكل endpoint. حركة المرور على خدمة single أو proxy أو browser التي طلبتها.
يتم تقييم خطتك الخاصة أولا، وهذا الترتيب هو العقد المعتمد وليس مجرد تفصيل تنفيذي. الحصص المشتركة هي موارد عامة، لذا فإن الطلب الذي كانت المنصة سترفضه حتما يجب ألا يستهلكها في طريقه إلى الرفض. أي حساب يرسل أكثر بكثير مما تسمح به خطته يتم إيقافه قبل أن يمس أي شيء يعتمد عليه الآخرون.
يحسب الفحصان 2 و 3 إجمالي حركة مرور FourA، وليس حركتك الخاصة. اعتبر الرفض من أي منهما بمثابة "FourA مشغولة"، وليس "لقد أرسلت أكثر من اللازم". يختص الفحص 1 بحسابك وحده، ولا يوجد أي شيء آخر على المنصة يؤثر عليه.
الرفض من أي من الفحصين المشتركين يعيد لحسابك كل ما احتسبه قبوله، مثل سعة الدقيقة وحصة المتصفح اليومية على حد سواء، لأن الطلب لم يصل أبدا إلى الواجهة الخلفية. كما أنه لا يحتسب ضمن فترة انتظار إعادة المحاولة الموضحة في Requests per minute أيضا: فقد رفضته سعة FourA، وليس خطتك.
لا تحتفظ POST /api/auto/ بأي حصة خاصة بها. الطلبات الفرعية من نوع Single و Proxy و Browser التي تنفذها نيابة عنك تمر بجميع الفحوصات الثلاثة مثل أي طلب آخر، وبالتالي فإن الدفعة المتوازية من طلبات auto تحتسب ضمن خطتك من خلال طلباتها الفرعية. (تعد أعداد طلباتك ومعدل نجاحك طلب auto نفسه مرة واحدة؛ بينما تظهر الطلبات الفرعية كمحاولات له.)
حدود الخطة
يستجيب حد الخطة بـ header من نوع X-FourA-Limit يحدد الحد الذي رفض الطلب. يوجد الرمز نفسه في body تحت reason، حتى تتمكن من التفريع بناء عليه دون قراءة headers. يحتوي كل body لحدود الخطة على error و reason و documentation؛ بينما تعتمد بقية الحقول على نوع الحد.
X-FourA-Limit |
الحالة | ما الذي نفد |
|---|---|---|
plan_limit_feature |
403 | الـ endpoint الذي طلبته، أو المعلمة exitCountries أو exitState أو exitCity أو exitAsn أو exitOs، ليست مشمولة في خطتك |
plan_limit_premium |
403 | exitClass: premium غير مشمول في خطتك، أو أن طلب Proxy يحدد exit location دون وجود رصيد premium traffic متبقٍ |
plan_limit_concurrency |
429 | الطلبات المتزامنة على هذا الـ endpoint |
plan_limit_rate |
429 | الطلبات في الدقيقة على هذا الـ endpoint |
plan_limit_browser_daily |
429 | طلبات المتصفح لليوم |
plan_limit_credits |
429 | الأرصدة المفوترة لفترة الفاتورة |
plan_limit_bandwidth |
429 | النطاق الترددي لفترة الفاتورة |
الأرقام المرتبطة بكل حد خاصة بخطتك، وتسردها علامة التبويب Limits & Features في Usage & Limits إلى جانب استخدامك الفعلي المباشر. لا تدمج هذه الأرقام برمجيا بشكل ثابت: يتضمن كل رفض الحد الأقصى الذي تسبب في الرفض.
الطلب المرفوض لا يستهلك أي رصيد. النتيجة هي rate_limit، وتتم فوترة success فقط.
الـ endpoint أو المعلمة غير مشمولة في الخطة
رمز 403 مع plan_limit_feature يعني أن الطلب استدعى شيئا لا تتضمنه الخطة. يتم إجراء التحقق قبل احتساب أي شيء، لذا لا يؤثر الطلب المرفوض على معدل طلباتك أو عداداتك اليومية.
{
"error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
يرد الرمز والحالة نفسهما على استدعاء POST /api/proxy/ الذي يحدد exitCountries أو exitState أو exitCity أو exitAsn أو exitOs في خطة لا تتضمن الاستهداف الجغرافي. تحدد سلسلة error اسم المعلمة:
{
"error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
"reason": "plan_limit_feature",
"documentation": "https://foura.ai/prices"
}
plan_limit_premium له نفس الهيكل بالنسبة لـ exitClass: premium في خطة لا تتضمن نقاط خروج premium. الخطة التي تتضمن نقاط خروج premium ولكنها استهلكت حركة مرور premium لهذه الفترة لا تُرفض، ما لم يحدد طلب Proxy موقع خروج معين: يُخدم الطلب من المجموعة القياسية (standard pool) ويُرجع الـ response القيمة exitClass: standard. لا تستهلك أي من الحالتين نقطة خروج premium. راجع exitClass.
لا يضبط أي من خطأي 403 القيمة Retry-After. الانتظار لن يغير النتيجة.
الطلبات المتزامنة
يتم احتساب التزامن (Concurrency) لكل endpoint: تتضمن خطتك حداً أقصى واحداً لـ Single، وواحداً لـ Proxy، وواحداً لـ Browser. الطلب الذي يتجاوز الحد يعود برمز 429 مع Retry-After: 1:
{
"error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
"reason": "plan_limit_concurrency",
"documentation": "https://foura.ai/prices",
"limit": 50,
"in_flight": 51,
"retry_after_seconds": 1
}
يحسب in_flight الـ request المرفوض أيضاً، لذا فإنه يقرأ قيمة تزيد بمقدار واحد على الأقل عن limit.
الحل هو تقييد التوازي (parallelism) لديك بدلاً من زيادة وتيرة إعادة المحاولة. الرد على رمز 429 بإعادة إرسال نفس الدفعة فوراً يؤدي إلى توليد 429 أخرى لكل استدعاء فيها. راجع تشغيل الـ Requests بالتوازي للاطلاع على نمط عملي.
عدد الـ Requests في الدقيقة
تتضمن باقات Single و Proxy حداً مسموحاً به في الدقيقة، ويتم قياسه عبر دقيقة منزلقة. لا تحتسب ضمن هذا الحد سوى الـ requests المقبولة: يتم استبعاد الـ request المرفوض، وبالتالي فإن الحساب الذي يرسل طلبات باستمرار بمعدل أعلى قليلاً من حده المسموح به تتم تلبية الحد المسموح به له بدلاً من رفض كل طلباته تقريباً.
{
"error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 613,
"retry_after_seconds": 17
}
retry_after_seconds هي المدة المتبقية حتى يتم قبول request إضافي، في حال لم ترسل أي شيء آخر في هذه الأثناء: ثانية واحدة على الأقل و120 ثانية كحد أقصى. يحمل header Retry-After القيمة نفسها.
تخضع إعادة محاولة الـ requests المرفوضة بسرعة أكبر من ذلك لقاعدة خاصة بها. عندما تتجاوز الـ requests التي رفضتها هذه الحصة خلال الدقيقة المنزلقة ضعف الحصة المسموح بها، يتم رفض الاستدعاء مع فترة توقف مؤقت مدتها 30 ثانية بدلا من ذلك:
{
"error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
"reason": "plan_limit_rate",
"documentation": "https://foura.ai/prices",
"limit_per_minute": 600,
"current_rate": 540,
"refused_last_minute": 1250,
"cooldown": true,
"retry_after_seconds": 30
}
لا تُحتسب عمليات الرفض أثناء فترة الإيقاف المؤقت، لذا ينتهي الإيقاف المؤقت تلقائيًا مع مرور الدقيقة، حتى لو استمر العميل في إعادة المحاولة. للتمييز بين الإيقاف المؤقت والحصة العادية، اقرأ cooldown بدلاً من نص error.
طلبات Browser في اليوم
لا يمتلك Browser حصة محددة لكل دقيقة. يقتصر حد الخطة على عدد طلبات Browser في اليوم، وتُحسب بدءًا من منتصف الليل بتوقيت UTC، ويحسب العداد كل طلب browser يتم قبوله، وليس الطلبات الناجحة فقط. إن استدعاء Browser الذي يفشل من جانب FourA عند 0 رصيد، مثل 503 Backend service unavailable، يستعيد خانته اليومية. تتضمن استجابات Browser وAuto التي لم ترفضها حدودك العداد والحد في الترويسات X-FourA-Browser-Used-Today وX-FourA-Browser-Limit-Per-Day: انظر Response Headers.
{
"error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
"reason": "plan_limit_browser_daily",
"documentation": "https://foura.ai/prices",
"limit_per_day": 300,
"used_today": 301
}
لا يتضمن هذا الرفض أي retry_after_seconds ولا ترويسة Retry-After، لأن فترة الانتظار تستغرق ساعات بدلاً من ثوانٍ. تعامل مع ذلك كتوقف وجدول التشغيل التالي عند منتصف الليل بتوقيت UTC.
رصيد فترة الفاتورة
يتم احتساب الرصيد المفوتر فقط، مما يعني احتساب الـ requests الناجحة فقط. عندما يصل إجمالي الرصيد المفوتر إلى الرصيد المتاح لك في هذه الفترة، يتم رفض أي requests إضافية حتى تتم إعادة تعيين الفترة أو تقوم بشراء المزيد.
{
"error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
"reason": "plan_limit_credits",
"documentation": "https://foura.ai/prices",
"used": 75000,
"hard_stop": 75000,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z"
}
hard_stop هو عدد الرصيد المحتسب الذي تتوقف عنده طلبات request خلال هذه الفترة. اقرأه من body بدلا من حسابه: فهو يتضمن بالفعل أي رصيد اشتريته بالإضافة إلى الخطة.
النطاق الترددي لفترة الفوترة
الخطط التي تتضمن حدا أقصى للنطاق الترددي ترفض طلبات request بمجرد وصول حركة المرور القياسية لهذه الفترة إليه. حركة المرور premium لها مخصصاتها الخاصة ولا تحتسب ضمن هذا الحد الأقصى. النطاق الترددي المشترى يحتسب بنفس طريقة النطاق الترددي المضمن، وتسرد سلسلة error ما هو متاح لك، وليس ما تتضمنه الخطة وحدها.
{
"error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
"reason": "plan_limit_bandwidth",
"documentation": "https://foura.ai/prices",
"used_bytes": 53687091200,
"limit_bytes": 53687091200,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z"
}
في كلا الحدين الدوريين، يُحدد retry_after_seconds بحد أقصى قدره 24 ساعة؛ ويمثل resets_at اللحظة الدقيقة التي تبدأ فيها الدورة التالية.
حقول حدود الخطة
| الحقل | النوع | موجود في | الوصف |
|---|---|---|---|
error |
string | الكل | رسالة مقروءة للمستخدم، تتضمن الحد المفروض عليك |
reason |
string | الكل | plan_limit_ متبوعا باسم الحد. نفس قيمة الترويسة X-FourA-Limit. |
documentation |
string | الكل | رابط لصفحة الخطط |
retry_after_seconds |
number | concurrency، rate، credits، bandwidth | مدة الانتظار. نفس قيمة الترويسة Retry-After. |
limit |
number | concurrency | الطلبات المتزامنة التي تسمح بها الخطة على نقطة النهاية تلك |
in_flight |
number | concurrency | الطلبات الجاري تنفيذها على نقطة النهاية تلك لحسابك، بما فيها الطلب المرفوض |
limit_per_minute |
number | rate | الطلبات في الدقيقة التي تسمح بها الخطة على نقطة النهاية تلك |
current_rate |
number | rate | الطلبات المحسوبة في الدقيقة المنزلقة، بما فيها الطلب المرفوض |
refused_last_minute |
number | rate pause | الطلبات المرفوضة من الحصة المحددة للدقيقة خلال الدقيقة المنزلقة. يظهر فقط عند الإيقاف المؤقت لمدة 30 ثانية. |
cooldown |
boolean | rate pause | تكون القيمة true عند الإيقاف المؤقت لمدة 30 ثانية بسبب إعادة المحاولة بسرعة كبيرة. غير موجود عند الرفض العادي لحصة الدقيقة. |
limit_per_day |
number | browser daily | طلبات المتصفح التي تسمح بها الخطة يوميا |
used_today |
number | browser daily | طلبات المتصفح المحسوبة اليوم، بما فيها الطلب المرفوض |
used |
number | credits | الأرصدة المفوترة حتى الآن في هذه الدورة |
hard_stop |
number | credits | الأرصدة المفوترة التي تتوقف عندها الطلبات في هذه الدورة |
used_bytes |
number | bandwidth | حركة المرور القياسية حتى الآن في هذه الدورة، بالبايت. حركة المرور المميزة (Premium) غير مدرجة. |
limit_bytes |
number | bandwidth | البايتات المتاحة في هذه الدورة |
resets_at |
string | credits، bandwidth | طابع زمني بتنسيق ISO 8601 لنهاية الدورة |
تستخدم حدود الخطة retry_after_seconds. بينما تستخدم حدود المنصة أدناه retryAfter. تحتاج أداة إعادة المحاولة إلى قراءة كليهما، أو قراءة ترويسة Retry-After، التي تحددها حدود الخطة وكذلك استجابة 503 API key check temporarily unavailable (راجع الأخطاء).
حدود المنصة
تتبع فحوصات المنصة أمرين لكل خدمة وأمرا إضافيا عبر جميع الخدمات:
- Concurrency: عدد الطلبات التي تعالجها FourA في نفس الوقت.
- RPM: عدد الطلبات التي استقبلتها FourA خلال آخر 60 ثانية.
يشترك جميع مستخدمي تلك الخدمة في كلا العدادين. يصف الحقلان current وlimits في الاستجابات أدناه المنصة، وليس حسابك. إذا كنت تريد معرفة أرقام حسابك، فاقرأ in_flight من استجابة حدود الخطة، أو افتح الاستخدام والحدود في لوحة التحكم.
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 Exceeded)
{
"error": "Service at capacity",
"status": 503,
"service": "proxy",
"retryAfter": 2,
"current": {
"concurrency": 500,
"rpm": 1200
},
"limits": {
"maxConcurrency": 500,
"maxRpm": 3000
}
}
تقوم الخدمة بتشغيل أقصى عدد مسموح به من الـ requests في الوقت نفسه. سيزول هذا خلال ثوانٍ.
الخدمة معطلة
عند خروج الخدمة مؤقتًا عن الخدمة لأغراض الصيانة، يُرجع الـ API الرمز 503 مع رسالة خطأ مختلفة:
{
"error": "Service disabled",
"status": 503,
"service": "single",
"retryAfter": 60,
"current": { "concurrency": 0, "rpm": 0 },
"limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
هذا ليس rate limit. الخدمة غير متاحة مؤقتا. تحقق من قيمة retryAfter وأعد المحاولة بعد انقضاء هذا العدد من الثواني. يُحل هذا الأمر عادة خلال دقائق.
يحمل كلا شكلي 503 نفس المفاتيح، لذا اعتمد في التفريع على سلسلة error ولا تعتمد أبدا على الحقول الموجودة. القيمة Service disabled تعني الصيانة، وService at capacity تعني التزامن.
في شكل الصيانة، تكون قيمة current.concurrency وcurrent.rpm دائما 0: تم رفض الـ request قبل قياس أي شيء.
حقول حدود المنصة
| الحقل | النوع | الوصف |
|---|---|---|
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 | الحد المشترك المسموح به للتزامن في الخدمة |
limits.maxRpm |
number | الحد المشترك المسموح به في الدقيقة للخدمة |
معالجة كل حالات الرفض باستخدام دالة مساعدة واحدة
يتم تعيين Retry-After عند حدود الخطة التي تستحق الانتظار، وتوجد retry_after_seconds في نصوصها، وتوجد retryAfter في نصوص المنصة. اقرأ الثلاثة بهذا الترتيب، وتوقف عند حدود الخطة التي لن يعالجها أي انتظار:
import time
import requests
# Plan limits that a short wait never clears.
STOP_ON = {
"plan_limit_feature",
"plan_limit_premium",
"plan_limit_browser_daily",
"plan_limit_credits",
"plan_limit_bandwidth",
}
def wait_seconds(resp, attempt):
header = resp.headers.get("Retry-After")
if header and header.isdigit():
return int(header)
try:
body = resp.json()
except ValueError:
return 2 ** attempt
return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
def fetch(url, api_key, max_retries=5):
for attempt in range(max_retries):
resp = requests.post(
"https://eu.api.foura.ai/api/single/",
headers={"X-API-Key": api_key, "Content-Type": "application/json"},
json={"method": "GET", "url": url},
)
limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")
if resp.status_code in (429, 503):
time.sleep(wait_seconds(resp, attempt))
continue
return resp
raise RuntimeError("Max retries exceeded")
الحصة اليومية لا تُستعاد إلا بعد ساعات، وحصة الفترة لا تُستعاد إلا بعد أيام، لذا تعامل معها كإيقاف بدلاً من انتظار. اقرأ resets_at من نص الاستجابة إذا أردت جدولة التشغيل التالي.
نصائح
- حدد الحد الأقصى لعدد الطلبات النشطة (in-flight) بدلاً من إعادة محاولة إرسال دفعة مرفوضة. عاصفة إعادات المحاولة تحوّل خطأ 429 واحداً إلى العديد.
- اقرأ
X-FourA-Limitأولاً. يخبرك في نص واحد ما إذا كان الحد خاصاً بك أو بالمنصة، ولا يحدده أي رفض من المنصة. - لا ترمز الأرقام بصورة ثابتة (hardcode). كل استجابة حد للخطة تتضمن السقف الذي رَفَضَها، ويعرض Usage & Limits جميع هذه الحدود.
- يتم تحديد
retryAfterفي حدود المنصة وفقاً للنوع: 2 ثانية للتزامن، و5 لـ RPM، و60 للصيانة. - طابق على
errorللتمييز بين حالتي 503. يحمل كلا الشكلينcurrentوlimits، لذا فإن فحص "هل تلك الحقول موجودة؟" يقرأ الصيانة على أنها مشكلة تزامن. - خطأ 403 مع
X-FourA-Limitيتعلق بخطتك، وليس بالموقع المستهدف. الموقع المستهدف لم يُجب أصلاً.
منفذ Proxy له أرقامه الخاصة
كل ما سبق يختص بـ JSON API. حركة المرور التي ترسلها عبر proxy.foura.ai تخضع لمجموعة منفصلة من أرقام الخطة، بوحدة قياس مختلفة: الأنفاق المفتوحة في وقت واحد، وعمليات فتح الأنفاق في الدقيقة، وحركة المرور القياسية لفترة الفاتورة. تأتي حالات الرفض هذه كحالة HTTP مصحوبة بـ header من نوع X-Foura-Error بدلاً من جسم JSON، نظراً لأن CONNECT لا يحتوي على body لوضعه فيه. راجع Proxy Port لجدول الحالات وHow Your Plan Is Metered لمعرفة المجمع الذي تُحتسب منه غيغابايت المنفذ.
ذو صلة
- Run Requests in Parallel: نمط عملي للتزامن المقيد
- Usage & Limits: كل حد للخطة بجانب استخدامك المباشر
- API Endpoints: مرجع المعلمات الكامل
- Error Handling: جميع أنواع الأخطاء والاستجابات
- Response Headers:
X-FourA-LimitوRetry-Afterوبقية العناصر - Troubleshooting: المشاكل الشائعة وحلولها