نتائج الطلبات

يتم تصنيف كل طلب إلى FourA API في نتيجة واحدة بالضبط، وكذلك كل نفق عبر منفذ proxy. يتم احتساب النتيجة مرة واحدة، في نهاية الاستدعاء، وتُسجل مقابل بيانات الاعتماد التي أجرته. تقرأ لوحة التحكم وموجز النشاط والفوترة لديك نفس الحقل.

فقط success يستهلك رصيداً. يتم احتساب حركة المرور المميزة (Premium traffic) بشكل منفصل عن الرصيد ولا تتبع النتيجة: راجع Billing Implications.

The Seven Outcomes

هذه هي النتائج السبع التي يمكن أن ينتهي إليها الطلب. يستخدم النفق خمسة منها: راجع Tunnels Use the Same Vocabulary أدناه.

Outcome	Layer	What it means
`success`	لا ينطبق	تم تسليم استجابة صالحة. يُحتسب ضمن حصتك القابلة للفوترة.
`application_error`	target	أرجع الهدف HTTP 200، ولكن نص الاستجابة احتوى على حقل خطأ، أو كان نص الاستجابة صفحة تحقق من البوت يتعرف عليها FourA.
`application_fail`	target	أرجع الهدف رمزاً لا يتبع 2xx لم تقبله قواعد `validate` الخاصة بك، أو لم يرجع أي استجابة على الإطلاق، بما في ذلك تعذر حل اسم مضيف الهدف.
`client_error`	caller	تم رفض طلبك قبل أن يغادر FourA. معلمات غير صالحة، أو قيمة proxy غير صحيحة، أو عنوان URL محمي ضد SSRF.
`rate_limit`	FourA	تم رفض الطلب قبل تنفيذه: بواسطة أحد حدود خطتك (رمز 403 لنقطة نهاية أو معلمة لا تتضمنها الخطة، أو 429 لاستنفاد الحصة المسموح بها)، أو بواسطة حد RPM المشترك للمنصة أو حد التزامن.
`service_error`	FourA	استجاب المحرك بخطأ في الخادم، أو لم يكن نص الاستجابة بتنسيق JSON صالح.
`service_fail`	FourA	فشلت شبكة FourA الخاصة: لم يستجب محركها في الوقت المحدد أو انقطع الاتصال، أو قمت أنت بقطع الاتصال.

يوضح عمود الطبقة (layer) الجهة المسؤولة:

نتائج target تتعلق بالموقع الذي استدعيته. وصل طلبك إلى FourA بنجاح، ووصل FourA إلى الهدف بنجاح. الهدف نفسه أرجع خطأ.
نتائج caller تعني أن طلبك لم يحظ بأي فرصة للتنفيذ. قم بإصلاح بنية الطلب.
نتائج FourA تقع على عاتقنا. أعد المحاولة، وتحقق من status page إذا استمرت.

إذا أرجع الموقع المستهدف 403، فإن النتيجة تكون application_fail وليست client_error. كان الاستدعاء الخاص بك سليم البنية، لكن الموقع رفض الطلب فحسب.

النجاح يعتمد على `validate`

بدون validate، تحدد API الطلب كـ success فقط عندما يرجع الهدف HTTP 200.

باستخدام validate، يتبع النجاح القواعد التي حددتها. إذا أبلغت API أن كلاً من 200 و 403 مقبولان لطلب معين، فسيتم إرجاع 403 كـ success. وسيصلك نص الاستجابة دون أي تغيير.

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://target.example/feed",
    "validate": {
      "status": { "accept": [200, 403] }
    }
  }'

في هذا الاستدعاء، تُحتسب استجابة 403 كـ success وتُفوتر كطلب واحد. أما استجابة 500 فتُحتسب كـ application_fail ولا تتم فوترتها.

ينطبق المنطق نفسه على validate.headers و validate.data. أي استجابة يقبلها المحرك وفقا لقواعدك تعود كـ success بغض النظر عن حالة HTTP.

هناك استجابة واحدة لا تكون أبدا success، مع أو بدون validate: استجابة HTTP 200 يحتوي جسمها على صفحة تحقق من الروبوتات يتعرف عليها FourA، مثل مهمة تحقق مرئي أو صفحة تطلب فقط من المتصفح تشغيل JavaScript. هذا الطلب يُعد application_error ولا تتم فوترته. لا يزال الجسم يصل إليك دون تغيير، ويحدد الترويسة X-FourA-Check-Page صفحة التحقق.

آثار الفوترة

النتيجة	خاضع للفوترة	يُحتسب ضمن الحصة
`success`	نعم	نعم
`application_error`	لا	لا
`application_fail`	لا	لا
`client_error`	لا	لا
`rate_limit`	لا	لا
`service_error`	لا	لا
`service_fail`	لا	لا

تتم فوترة الطلبات التي قدمت البيانات التي طلبتها فقط. حالات الفشل من جانب FourA، أو من جانب الهدف، أو من جانبك، كلها مجانية.

الجدول يخص الرصيد. حركة المرور premium تُحتسب بشكل منفصل عنها: الطلب الذي حاول استخدام منفذ خروج premium يحتسب حركة المرور التي نقلتها تلك المحاولة، أيا كانت النتيجة، لأن منفذ الخروج قد استُخدم في الحالتين. المحاولة التي كانت لا تزال قيد التشغيل عند استجابة منفذ خروج آخر يتم إيقافها فورا، وتُحتسب حركة المرور التي نقلتها حتى ذلك الحين أيضا.

حركة المرور القياسية لا تتبع النتيجة أيضا: في خطة تتضمن حدا لحجم نقل البيانات، تُحتسب حركة مرور كل طلب ضمن هذا الحد. الطلب الذي رُفض بسبب أحد حدود خطتك لا يحتسب أي حركة مرور.

الأنفاق تستخدم المفردات نفسها

النفق عبر منفذ proxy ينتهي بإحدى هذه النتائج أيضا، لذا تغطي مجموعة تسميات واحدة كلا المنتجين. يمكن أن تحدث خمس نتائج فقط من أصل سبع، لأن نتيجتي target تتطلبان أن يكون FourA قد عاين استجابة الهدف، واستجابة النفق هي حركة المرور المشفرة الخاصة بك.

النتيجة	في النفق، يعني هذا
`success`	فُتح النفق واستلمته أداتك.
`client_error`	لن يفتح FourA هذا النفق: عنوان خاص أو محجوز، أو منفذ لا يخدمه.
`rate_limit`	تم الوصول إلى أحد حدود خطتك (الأنفاق المفتوحة في وقت واحد، أو فتحات النفق في الدقيقة، أو حركة المرور القياسية للفترة، أو حركة مرور premium لا تملكها)، أو كان المنفذ نفسه بكامل طاقته أو معدل فتحه.
`service_error`	لم يتوفر لدى FourA منفذ خروج لما طلبته. مؤقت عادة.
`service_fail`	تعذر الوصول إلى الهدف عبر أي منفذ خروج جربه FourA: خطأ DNS، أو انتهاء المهلة، أو رفض الاتصال.
`application_error`	لا يحدث أبدا في النفق.
`application_fail`	لا يحدث أبدا في النفق.

يتضمن الرفض أيضًا سببًا موجزًا، وتعرضه لوحة التحكم بمصطلحاتك الخاصة بدلًا من مصطلحاتنا. الخيار الذي لا تستطيع FourA الوفاء به يتم الرد عليه عبر 400 على الاتصال نفسه ولا يسجل أي صف، لذا لا يظهر هنا نهائيًا.

السبب على الشاشة	ما الذي نفد
port not in plan	خطتك لا تتضمن منفذ الـ proxy
tunnels at once	كانت جميع الأنفاق التي تسمح بها خطتك قيد الاستخدام في الوقت نفسه
openings per minute	تم استنفاد عمليات فتح الأنفاق المتاحة لخطتك خلال هذه الدقيقة
traffic used up	تم استنفاد حركة البيانات لخطتك خلال هذه الفترة
premium not available	حركة البيانات من الفئة Premium غير متاحة في خطتك حاليًا
port was full	المنفذ نفسه وصل إلى طاقته الاستيعابية القصوى أو معدل الفتح الأقصى. أعد المحاولة بعد لحظات.
port not served	لا تفتح FourA أنفاقًا إلى هذا المنفذ
private address	لا يمكن الوصول إلى العناوين الخاصة والمحجوزة

لا تتم فوترة أي شيء يخص النفق عبر الرصيد (credits)، لأن النفق ليس لديه request يمكن خصم التكلفة عليه. بدلاً من ذلك، يقيس المنفذ البايتات. راجع كيفية قياس استهلاك خطتك.

قراءة النتائج في لوحة التحكم

يظهر كل request ينفذه مفتاح API الخاص بك في موجز Activity مع تسمية النتيجة الخاصة به. تجمع صفحتا Metrics وOverview الحقل نفسه للمخططات الدائرية والمخططات الزمنية.

عند تصفية Activity حسب النتيجة، يمكنك أيضًا التركيز على endpoint واحد (Auto، Single، Proxy Finder، Browser) لمعرفة ما إذا كانت فئة معينة من الفشل خاصة بأحدها. قم بتبديل Product في الصفحة إلى Proxy وستقوم شارات النتائج نفسها بتصفية الأنفاق الخاصة بك.

قواعد إعادة المحاولة الموجهة

سياسة إعادة محاولة أولية تستند إلى النتائج:

النتيجة	هل إعادة المحاولة آمنة؟	متى
`success`	لا ينطبق	لديك الـ response بالفعل.
`application_error`	أحيانًا	اقرأ نص الخطأ من الهدف. بعض الأخطاء مؤقت، وأغلبها ليس كذلك. إذا تم تعيين `X-FourA-Check-Page`، فإن الموقع عرض صفحة تحقق: أرسل الـ URL إلى Auto، والذي يتعامل مع صفحة التحقق كخطوة يجب تجاوزها، وليس كإجابة نهائية.
`application_fail`	أحيانًا	إذا كان الهدف يطبق عليك rate limit، فقم بإبطاء المعدل. وإذا كان يحظرك، فقم بالتبديل إلى الـ endpoint الخاص بـ Proxy أو Browser.
`client_error`	لا	سيفشل الـ request مرة أخرى بالطريقة نفسها. قم بتصحيح المدخلات.
`rate_limit`	يعتمد على الحالة	التزم بمدة الانتظار التي يمنحها الـ response: سواء `Retry-After`، أو `retry_after_seconds`، أو `retryAfter`. عند `plan_limit_browser_daily`، توقف حتى منتصف الليل بتوقيت UTC؛ وعند `plan_limit_credits` أو `plan_limit_bandwidth`، توقف حتى `resets_at`؛ وعند `plan_limit_feature` أو `plan_limit_premium`، قم بتعديل الـ request.
`service_error`	نعم	تراجع أسي قصير (exponential backoff).
`service_fail`	نعم	مماثل لـ `service_error`.