المشكلات الشائعة

حلول للمشكلات الأكثر شيوعًا عند استخدام FourA API.

محتوى فارغ أو غير مكتمل

العَرَض: ترجع API حالة 200 ولكن الحقل data فارغ أو يفتقر إلى المحتوى المتوقع.

السبب: تستخدم الصفحة المستهدفة JavaScript لعرض المحتوى بعد تحميل الصفحة الأولي.

الحل: انتقل من endpoint الفردي إلى browser endpoint. استخدم checkText للتحقق من تحميل المحتوى:

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

ملاحظة: يُرجع endpoint المتصفح المحتوى في الحقل body (وليس data).

403 Forbidden أو صفحات التحقق

العَرَض: تُرجع الـ API كود HTML يحتوي على صفحة تحقق أو صفحة تم رفض الوصول.

السبب: اكتشف الموقع المستهدف أن الطلب مؤتمت وقام بحظره.

الحل: استخدم proxy endpoint للتدوير التلقائي لعنوان IP:

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

إذا استمرت المشكلة، فقم بزيادة maxTries لمنح تدوير proxy محاولات إضافية.

يصل رمز 403 الذي يعيده الهدف كاستجابة HTTP 200 مع status: 403 داخل نص الاستجابة body. أما رمز 403 على مستوى الاستدعاء نفسه، مع ترويسة X-FourA-Limit، فهو أمر مختلف: راجع 403 ليس ضمن خطتك.

أخطاء انتهاء المهلة Timeout Errors

العَرَض: تفشل الطلبات requests مع ظهور خطأ انتهاء المهلة timeout.

السبب: تستغرق الصفحة المستهدفة وقتا أطول للتحميل مقارنة بالمهلة المحددة timeout.

الحل: زيادة timeout_ms (القيمة الافتراضية هي 15s للوضع single، و30s للوضع browser، و45s للوضع proxy):

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'

بالنسبة لطلبات browser، تحقق أيضا من أن قيمة checkText تظهر بالفعل على الصفحة. أي خطأ إملائي يؤدي إلى فشل الاستدعاء مع checkText:<your text> not found.

403 غير مشمول في خطتك

العَرَض: تُرجع API الرمز 403 مع ترويسة X-FourA-Limit وreason بقيمة plan_limit_feature أو plan_limit_premium.

{
  "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"
}

السبب: خطتك لا تتضمن الـ endpoint الذي استدعيته أو المعامل الذي أرسلته. يغطي plan_limit_feature أي endpoint مستبعد، ويغطي exitCountries، وexitState، وexitCity، وexitAsn، أو exitOs دون استهداف جغرافي. ويغطي plan_limit_premium القيمة exitClass: premium دون نقاط خروج مدفوعة، وكذلك طلب Proxy يحدد موقع خروج بمجرد استنفاد حركة المرور المدفوعة لديك. لم يتم الاتصال بالهدف مطلقًا، ولم يتم استهلاك أي شيء.

الحل: أزل المعامل، أو استدعِ endpoint تتضمنه خطتك، أو قم بالترقية. تسرد علامة التبويب الحدود والميزات في الاستخدام والحدود ما تتضمنه خطتك. لا تُعد المحاولة دون تغيير: لم يتم ضبط Retry-After لأن الانتظار لن يغير النتيجة.

429 طلبات كثيرة جدًا

العَرَض: تُرجع الـ API الرمز 429.

السبب: رفض أحد الفحصين الاستدعاء، وتوضح الاستجابة أيهما كان السبب. إذا كانت تتضمن ترويسة X-FourA-Limit، فهذا يعني الوصول إلى أحد حدود خطتك: الطلبات المتزامنة أو الطلبات في الدقيقة على هذا الـ endpoint، أو طلبات Browser لليوم، أو الرصيد أو سعة النطاق الترددي لفترة الفوترة. إذا لم تكن هناك مثل هذه الترويسة، فإن الحصة المشتركة للمنصة في الدقيقة لهذه الخدمة كانت ممتلئة، وهو أمر يتعلق بحركة مرور FourA وليس بحركتك.

الحل: اقرأ X-FourA-Limit أولاً. انتظر عندما يكون الحد على بُعد ثوانٍ وتوقف عندما لا يكون كذلك. حدود الخطة التي يزول مفعولها بالانتظار تضع الثواني في ترويسة Retry-After وفي retry_after_seconds؛ أما الحد المشترك فيضعها في retryAfter:

import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)

إذا كان الترويسة تتضمن plan_limit_concurrency أو plan_limit_rate، فإن الحل هو تحديد سقف لعدد المكالمات المفتوحة وعدد المكالمات التي تبدأها في الدقيقة بدلا من تكرار المحاولة بكثافة أكبر. إعادة إرسال دفعة مرفوضة على الفور ستؤدي إلى رفض الدفعة بأكملها مجددا. لا تُحسب المكالمات المرفوضة ضمن الحد الأقصى الخاص بك في الدقيقة، ولكن إذا استمر وصولها بأكثر من ضعف هذا الحد، فستتحول حالات الرفض إلى فترة تهدئة: يحتوي نص استجابة 429 على cooldown: true ويطلب منك التوقف مؤقتا لمدة 30 ثانية (retry_after_seconds: 30). يوضح تشغيل الطلبات بالتوازي النمط المناسب، ويعرض قسم الاستخدام والحدود في لوحة التحكم عداداتك المباشرة بجانب الحدود القصوى الخاصة بك.

503 الخدمة غير متوفرة

العَرَض: تُرجع واجهة برمجة التطبيقات (API) الحالة 503.

السبب: يحدث هذا في ثلاث حالات:

  1. الخدمة وصلت إلى أقصى طاقتها الاستيعابية. يقوم FourA بالفعل بتشغيل أقصى عدد مسموح به من الطلبات في وقت واحد على هذا المحرك، محسوبا عبر جميع الزيارات وليس زياراتك وحدك. Service at capacity في حقل error. عادة ما يتم حل المشكلة خلال ثوانٍ.
  2. الخدمة معطلة مؤقتا. هناك فترة صيانة جارية. Service disabled في حقل error.
  3. لا يمكن لـ FourA التحقق من مفتاحك في الوقت الحالي. API key check temporarily unavailable في حقل error، مع Retry-After: 5. مفتاحك سليم.

تتضمن جميع الحالات الثلاث حقلا retryAfter في الاستجابة. لا تعود أي منها إلى حدود الخطة: ترد حدود خطتك دائما بترويسة X-FourA-Limit مع رمز 403 أو 429، ولا تستخدم 503 على الإطلاق.

الحل: انتظر لمدة retryAfter ثانية، ثم أعد المحاولة:

import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

يعني الخطأ 503 عند بلوغ السعة القصوى أن FourA مشغولة، لذا فإن التراجع وإعادة المحاولة هما الحل الكامل. أما إذا تم رفضك بالرمز 429 وX-FourA-Limit بدلا من ذلك، فهذا الخطأ من جانبك: قلل عدد الـ requests المتوازية في الـ pipeline الخاصة بك.

504 انتهاء مهلة المصدر الرئيسي

العَرَض: تُرجع الـ API الرمز 504 مع {"error": "Upstream timeout"}.

السبب: لم تكتمل المهمة خلال المهلة الزمنية المحددة للـ request. الهدف البطيء، أو حل التحدي لأول مرة، أو الصفحات الكبيرة جدا قد تسبب ذلك جميعا. هذه ليست مشكلة في مفتاحك، أو معلماتك، أو الـ proxy الخاص بك.

الحل: امنح الاستدعاء مزيدا من الوقت، أو أعد المحاولة. تنتظر FourA قيمة timeout_ms الخاصة بك بالإضافة إلى هامش صغير، لذا فإن زيادتها تمدد وقت الانتظار فعليا:

{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}

بالنسبة لـ /api/auto/ على هدف محمي، يمكن أن يستغرق أول استدعاء بارد عشرات الثواني. يغطي timeout_ms الخاص به كامل السلسلة ويقبل حتى 180000.

عندما ينفد هذا الوقت المحدد من /api/auto/ نفسه، يظل الاستدعاء يجيب بـ HTTP 200. يحمل نص الاستجابة error يبدأ بـ time budget exhausted، ويكون status عادة 504 (قد تترك محاولة فاشلة سابقة حالتها الخاصة هناك بدلا من ذلك). ارفع قيمة timeout_ms أو أعد المحاولة.

502 الخادم المصدر غير متاح

العَرَض: ترجع API الرمز 502 مع {"error": "Upstream unavailable"}، أو 503 مع {"error": "Backend service unavailable"}.

السبب: لم يتمكن FourA من الوصول إلى محركه الخاص (Upstream unavailable)، أو لم يقدم المحرك إجابة صالحة للاستخدام (Backend service unavailable)، وعادة ما يكون ذلك بسبب إعادة تشغيل أحد النماذج. في /api/browser/، تنتظر الصفحة حتى 10 ثوان للحصول على متصفح متاح عندما تكون جميعها مشغولة، والصفحة التي تظل قيد الانتظار بعد ذلك ترجع كخطأ 503 هذا.

الحل: أعد المحاولة مع فترة تراجع قصيرة. يتم تصنيف كليهما كـ service_error، وتتم فوترة success فقط، لذا لن تكلفك إعادة المحاولة أي شيء إضافي. إذا استمر الأمر لأكثر من دقيقة أو دقيقتين، فتحقق من صفحة الحالة.

أخطاء المصادقة 401

العَرَض: يرجع كل request الرمز 401 Unauthorized.

قائمة التحقق:

  1. تحقق من أن header هو X-API-Key: YOUR_API_KEY (وليس Authorization: Bearer أو Api-Key)
  2. تحقق من عدم وجود مسافات بيضاء زائدة أو أسطر جديدة في API key الخاص بك
  3. أنشئ مفتاحا جديدا من لوحة التحكم إذا كان المفتاح الحالي قد تعرض للاختراق

400 طلب غير صالح

العَرَض: يرجع استدعاء POST /api/single/ أو /api/proxy/ أو /api/browser/ الرمز 400 مع {"error": "Invalid request: <field>: <reason>; ..."}.

السبب: يوجد حقل مفقود في نص request الخاص بك، أو بنوع غير صحيح، أو خارج النطاق المسموح. تحدد الرسالة اسم كل حقل لم تتمكن من قبوله والسبب، حتى خمسة حقول، متبوعة بـ and N more عند وجود حقول أخرى. لم يتم جلب أي شيء، والنتيجة هي client_error، ولا يتم استهلاك أي رصيد.

الحل: أصلح الحقول المحددة وأرسل request مرة أخرى. سيتلقى نفس النص نفس الخطأ 400، لذا لا تعد المحاولة دون تعديل. يسرد مرجع endpoint كل حقل مع نوعه والقيود الخاصة به. في /api/auto/، يرجع نفس الخطأ كـ HTTP 200 مع status: 400 والسبب في error.

400 الهدف يشير إلى عنوان IP خاص أو محجوز

العَرَض: ترجع API الرمز 400 مع Refusing to fetch <target>: target resolves to a private or reserved IP range قبل أن يغادر request خدمة FourA.

السبب: يشير url الخاص بك إلى نطاق IP خاص أو استرجاع داخلي (loopback) أو محجوز (RFC 5735 أو RFC 6598 أو نطاقات IPv6 المحجوزة). ترفض FourA هذه الأهداف حتى لا يمكن استخدام شبكتها للوصول إلى مضيفين داخليين.

الحل: اجلب URL عاما. إذا كنت تختبر، فاستخدم هدفا عاما مثل https://example.com أو https://httpbin.org/get. إذا كان هدفك المقصود هو خدمة تديرها، فقم بإتاحتها على اسم مضيف عام أولا.

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

لا يتم رفض اسم المضيف الذي يتعذر البحث عنه. يعود الطلب كرمز HTTP 200 مع status: 0 والسبب (could not resolve <host>: <reason>)، مثل أي هدف لا يمكن لـ FourA الوصول إليه، ولا يتم احتساب تكلفة عليه.

400 مسافة في الـ URL

العَرَض: يرجع Single أو Proxy أو Auto الرمز 400 مع invalid URL: it contains a space; encode it as %20 (the URL as sent: "...") قبل أن يغادر الطلب FourA.

السبب: يحتوي الـ URL على مسافة أو رمز تحكم بداخله، وغالبا ما يكون رابطا مأخوذا من صفحة كما كُتب (javascript: void(0)، رابط مشاركة يحتوي على نص). لا يتم جلب أي شيء، وتكون النتيجة client_error، ولا يتم استهلاك أي رصيد.

الحل: قم بترميز الـ URL قبل إرساله (المسافة هي %20)، وتخط الروابط التي ليست صفحات، مثل روابط javascript:. يجلب المتصفح مثل هذا الـ URL بالطريقة التي يتبعها Chrome.

400 الهدف هو FourA API نفسها

العَرَض: ترجع الـ API الرمز 400 مع Refusing to fetch <url>: that is the FourA API itself, not a page. قبل أن يغادر الطلب FourA.

السبب: يشير url الخاص بك إلى api.foura.ai أو eu.api.foura.ai. عادة ما يقوم زاحف الويب بذلك عندما يحل رابطا نسبيا من صفحة مقابل عنوان الـ API URL بدلا من عنوان الـ URL الخاص بالصفحة نفسها، وبالتالي يتحول /category/news/ إلى https://eu.api.foura.ai/category/news/. لا يتم جلب أي شيء ولا يتم استهلاك أي رصيد.

الحل: قم بحل كل رابط مقابل الـ URL الخاص بالصفحة التي أتى منها قبل إرساله، على سبيل المثال باستخدام urljoin(page_url, href) في Python. نقطة نهاية Inspect endpoint (/inspect) هي العنوان الوحيد على مضيف الـ API الذي يمكنك جلبه عبر FourA.

no_eligible_proxy عند استخدام exitCountries

العَرَض: يرجع استدعاء /api/proxy/ مع exitCountries الرمز HTTP 200 مع غلاف خطأ JSON:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

السبب: لا يحتوي تجمع proxy الحالي على أي نقطة خروج صالحة للعمل يتطابق بلدها الظاهر للهدف مع قائمتك المسموحة. لا يتراجع التجمع القياسي أبداً إلى بلد غير مطلوب عند تعيين exitCountries. بدون exitCountries، تُرجع الحالة نفسها استجابة {"error": "Failed"}: لم تعثر FourA على أي نقطة خروج لتجربتها، لذا أعد المحاولة بعد بضع ثوانٍ.

أي request يحدد موقع خروج (exitState أو exitCity أو exitAsn أو exitOs أو exitLifetimeMin، مع exitClass: premium) يمر عبر نقاط خروج premium فقط. عندما لا يتبقى لدى FourA أي نقطة خروج premium لتجربتها لهذا الطلب، ينتهي الاستدعاء بالرمز "error": "No premium exit answered for this request" مع رمز code: no_eligible_proxy نفسه.

الحل: احتفظ بالنطاق المطلوب وأعد المحاولة لاحقاً. يتم تحديث التجمع كل 10 دقائق تقريباً، لذا فإن البلد الذي لا يتوفر له أي تطابق حالياً غالباً ما يتوفر له تطابق خلال ساعة.

import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")

لا تقم بتوسيع قائمة الدول إلا إذا تغيرت متطلبات الدولة في سير عملك بالفعل. يمكن أن يؤدي الرجوع التلقائي الصامت إلى دول أخرى إلى كسر المنطق المعتمد على الموقع الجغرافي لاحقًا.

تم رفض ملف تعريف المتصفح (Browser Profile)

العَرَض: يعود الاستدعاء بـ unknown profile '<id>' أو no profile matches browser=... أو browser profile selection requires unblocker:true.

السبب: قيمة profile أو browser أو os أو version التي أرسلتها ليست موجودة في الكتالوج، أو أنك أرسلت قيمة مع unblocker: false.

الحل: راجع GET /api/profiles للاطلاع على الكتالوج الحالي، واختر منه، واحتفظ بتفعيل unblocker عند اختيار متصفح.

نص الاستجابة (Response Body) يظهر كنص غير مفهوم

العَرَض: يحتوي data الخاص بالاستجابة (أو body) على نصوص مشوهة أو أحرف غير مقروءة عندما يستخدم الهدف ترميز أحرف غير UTF-8.

السبب: يقوم FourA افتراضيًا بفك ترميز نصوص الاستجابة تلقائيًا إلى UTF-8 استنادًا إلى ترويسة Content-Type الخاصة بالهدف أو علامة <meta charset> في HTML. إذا أرسل الهدف معلومات غير دقيقة حول ترميز الأحرف الخاص به، فستحصل على نص مشوه.

الحل: للحمولات الثنائية (الصور، أو protobuf، أو الصوت الخام)، اضبط returnBuffer: true في الـ request. بعد ذلك، يقوم كل من Single وProxy بإرجاع data ككائن يحتوي على البايتات الخام، {"type": "Buffer", "data": [<byte values>]}، دون تطبيق أي تحويل لترميز الأحرف.

{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}

بالنسبة للأهداف النصية التي تصرح عن charset الخاص بها بشكل غير صحيح، قم بفك ترميز البايتات الخام بنفسك: قم بالجلب باستخدام returnBuffer: true، واقرأ قيم البايتات في data.data، ثم فك ترميزها باستخدام الـ charset الصحيح.

HTML غير متوقع بدلا من JSON

العَرَض: كنت تتوقع JSON من الموقع المستهدف لكنك تلقيت HTML.

السبب: قد تقدم الصفحة المستهدفة محتوى مختلفا بناء على الـ headers.

الحل: أضف Accept header وقم بتمكين unblocker للحصول على browser headers واقعية:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'

يمكنك أيضاً تعيين tryJsonData إلى true لكي يقوم FourA بتحليل استجابات JSON تلقائياً.

محتوى الرد هو صفحة اختبار أمني وليس المحتوى المطلوب

العَرَض: نجح الاستدعاء، وstatus هو 200، لكن data (أو body) هو فحص روبوتات وليس الصفحة التي أردتها.

السبب: شغّل الهدف فحص روبوتات واجهه FourA لكنه تعذر تجاوزه. توضح الاستجابة ذلك: يُرجع Single وProxy القيمة defense مع solved: false، ويُرجع Browser القيمة defenseSolved: false مع اسم المزود في defenses.present.

الحل: تحقق من defense.vendor أولاً، ثم صعد الإجراء. جرّب ملف تعريف متصفح مختلفاً في Single، أو انتقل إلى Proxy للحصول على مخرج مختلف، أو استخدم Browser لتشغيل JavaScript. مرجع الحقول الكامل وقائمة المزودين: فحوصات الموقع.

أضف سلسلة نصية فرعية عبر validate.data.accept لا تظهر إلا في الصفحة الحقيقية. صفحة الفحص التي يتعرف عليها FourA لا تُعتبر ناجحة أبداً: فهي تُرجع ترويسة X-FourA-Check-Page ولا يتم احتساب تكلفتها. بدون validate، تُحسب صفحة الفحص التي لم يتعرف عليها FourA والمُرجعة برمز HTTP 200 كعملية ناجحة، وستكتشف ذلك في مرحلة لاحقة بدلاً من وقت الاستدعاء.

ما زلت تواجه مشكلة؟

إذا لم ينجح أي من الحلول أعلاه:

  1. تحقق من صفحة الحالة لمعرفة ما إذا كانت هناك أي حوادث جارية
  2. راجع مقاييس طلباتك في لوحة التحكم
  3. تواصل مع الدعم عبر support@foura.ai مع تفاصيل طلبك (قم بتضمين X-FourA-Request-Id من الاستجابة الفاشلة)

الخطوات التالية

آخر تحديث: 13 نوفمبر 2026