التوثيق › استكشاف الأخطاء › المشاكل الشائعة

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

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

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

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

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

الحل: انتقل من single 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"
  }'

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

صفحات 403 Forbidden أو Captcha

الأعراض: ترجع API ملف HTML يحتوي على تحدي captcha أو صفحة تم رفض الوصول إليها.

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

الحل: استخدم 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 محاولات أكثر.

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

الأعراض: تفشل requests بسبب خطأ انتهاء المهلة (timeout).

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

الحل: قم بزيادة timeout_ms (الافتراضي هو 15 ثانية لـ single، و30 ثانية لـ browser، و45 ثانية لـ 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 requests، تحقق أيضاً من أن قيمة checkText تظهر بالفعل على الصفحة. أي خطأ إملائي سيؤدي دائماً إلى حدوث timeout.

429 Too Many Requests (حد RPM)

الأعراض: ترجع API حالة 429 مع رسالة "rate limit exceeded".

السبب: لقد تجاوزت حد requests-per-minute (RPM). يختلف هذا عن حدود التزامن (concurrency) (انظر 503 أدناه).

الحل: استخدم حقل retryAfter من response للانتظار للوقت المناسب قبل إعادة المحاولة:

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

تحقق من استخدامك الحالي في Dashboard لمعرفة rate limits الخاصة بك.

503 Service Unavailable

الأعراض: ترجع API حالة 503.

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

  1. الوصول إلى حد التزامن (Concurrency). لديك عدد كبير جداً من requests المتزامنة قيد التشغيل. يختلف هذا عن 429، الذي يحد من requests في الدقيقة. مع 503، لم تتجاوز حد RPM الخاص بك، ولكنك وصلت إلى الحد الأقصى لعدد requests التي يمكن تشغيلها في نفس الوقت.
  2. الخدمة معطلة مؤقتاً. هناك أعمال صيانة قيد التنفيذ حالياً.

تتضمن كلتا الحالتين حقل retryAfter في response.

الحل: انتظر لعدد ثوانٍ مساوٍ لـ 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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

إذا كنت تواجه حدود التزامن 503 بانتظام، فقم بتقليل عدد requests المتوازية في نظام الكشط (scraping pipeline) الخاص بك، أو تحقق من حد التزامن لخطة اشتراكك في Dashboard.

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

الأعراض: يرجع كل request حالة 401 Unauthorized.

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

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

ملف 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 responses تلقائياً.

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

إذا لم تنجح أي من الحلول المذكورة أعلاه:

  1. تحقق من صفحة الحالة لمعرفة ما إذا كانت هناك أي أعطال جارية
  2. راجع مقاييس request الخاصة بك في Dashboard
  3. اتصل بالدعم الفني على support@foura.ai مع تزويدهم بتفاصيل request الخاصة بك

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

آخر تحديث: 27 أبريل 2026