نتائج الطلبات
يتم تصنيف كل request إلى FourA API إلى نتيجة واحدة بالضبط، وينطبق الأمر نفسه على كل نفق عبر منفذ proxy. يتم احتساب النتيجة مرة واحدة عند نهاية الاستدعاء، وتُسجَّل مقابل بيانات الاعتماد التي أجرته. تقرأ لوحة التحكم، وسجل النشاط، ونظام الفوترة لديك الحقل نفسه.
فقط success يستهلك الرصيد. يتم احتساب حركة المرور المتميزة (Premium) بمعزل عن الرصيد ولا تتبع النتيجة: راجع الآثار المترتبة على الفوترة.
النتائج السبع
هذه هي النتائج السبع التي يمكن أن ينتهي إليها أي request. يستخدم النفق خمس نتائج منها: راجع الأنفاق تستخدم نفس المفردات أدناه.
| النتيجة | الطبقة | المعنى |
|---|---|---|
success |
غير متاح | تم تسليم response صالح. يُحتسب ضمن حصتك الخاضعة للفوترة. |
application_error |
target | أرجع الهدف كود HTTP 200، ولكن نص الاستجابة احتوى على حقل خطأ، أو كان النص عبارة عن صفحة فحص برامج روبوت أو صفحة رفض يتعرف عليها FourA. |
application_fail |
target | أرجع الهدف حالة أخرى غير 200 لم تقبلها قواعد validate الخاصة بك أو أنك لم ترسل validate لها، أو لم يتم تلقي أي استجابة على الإطلاق، بما في ذلك تعذر حل اسم مضيف الهدف. |
client_error |
caller | تم رفض الـ request الخاص بك قبل مغادرته FourA. معلمات غير صالحة، أو قيمة proxy غير صحيحة، أو URL محمي ضد SSRF. |
rate_limit |
FourA | تم رفض الـ request قبل تنفيذه: إما بواسطة أحد حدود خطتك (رمز 403 لـ endpoint أو معلمة لا تتضمنها الخطة، أو 429 لانتهاء الحصة المخصصة)، أو بسبب حد RPM المشترك للمنصة أو حد التزامن المسموح به. |
service_error |
FourA | استجاب المحرك بخطأ في الخادم، أو لم يكن نص الاستجابة بصيغة JSON صالحة. |
service_fail |
FourA | فشلت شبكة FourA الخاصة: لم يستجب المحرك في الوقت المحدد أو انقطع الاتصال، أو قمت أنت بقطع الاتصال. |
يوضح عمود الطبقة الطرف المسؤول:
- نتائج target تتعلق بالموقع الذي استدعيته. وصل الـ request إلى FourA بنجاح، ووصل FourA إلى الهدف بنجاح. الهدف نفسه هو من أرجع الخطأ.
- نتائج caller تعني أن الـ request لم تكن لديه أي فرصة للنجاح من الأساس. قم بإصلاح بنية الـ request.
- نتائج FourA تقع مسؤوليتها علينا. أعد المحاولة، وتحقق من صفحة الحالة إذا استمرت المشكلة.
الموقع المستهدف الذي يُرجع 403 يُصنف كـ application_fail، وليس client_error. كان استدعاؤك صحيح البنية، والموقع فقط هو من رفض.
كيف يبدو الاستدعاء الفاشل
الاستدعاء الذي وصل إلى FourA وتم تنفيذه يعود بالحالة HTTP 200 بغض النظر عما حدث بعد ذلك. لا يستخدم أي حالة HTTP أخرى إلا الرفض الذي يحدث قبل عملية الجلب (400، 401، 403، 413، 429) أو الفشل من جانب FourA نفسه (5xx). لذلك، تُقرأ النتيجة من نص الاستجابة، وليس من حالة بروتوكول النقل.
| Body | ماذا حدث | النتيجة |
|---|---|---|
status: 200، headers، data، بدون error |
تم تسليم الصفحة. | success |
status بخلاف 200، headers، data، بدون error |
استجاب الهدف ولم ترسل أي validate. إجابته موجودة في data. |
application_fail |
status بخلاف 200، headers، data و error |
استجاب الهدف ورفضته قواعد validate الخاصة بك، على سبيل المثال Status 404 is not in accept list 200. |
application_fail |
status: 200، headers، data و error |
استجاب الهدف برمز HTTP 200 ورفضته قواعد validate الخاصة بك، على سبيل المثال Data not in accept list ["product"]. |
application_error |
error و total_time فقط، بدون status، بدون data |
لم يستجب الهدف عبر HTTP مطلقًا: تم الوصول إلى حد إعادة التوجيه (Number of redirects hit maximum amount)، أو انتهت مهلة الاتصال أو القراءة، أو تمت إعادة تعيين الاتصال، أو كان الرد فارغًا. النص هو السبب الخاص بالمحرك. |
application_fail |
status: 0 و error، لا شيء آخر |
يتعذر حل اسم المضيف: could not resolve <host>: <reason>. لم يعمل أي محرك، وفي وضع Auto لا يوجد meta. إعادة المحاولة لن تغير النتيجة حتى يتغير DNS. |
application_fail |
حلقة إعادة توجيه، كما يراها الصف الخامس:
{
"error": "Number of redirects hit maximum amount",
"total_time": 0.808
}
في POST /api/proxy/، يحمل الاستدعاء الذي يستنفد المحاولات error: Download maxTry limit reached وattemptReport مع التعدادات (انظر API Errors). في POST /api/auto/، يحمل التدرج الذي تم تشغيله وفشل status وerror وattempts وattemptReport مع الأسباب، وتعيين meta.rung إلى fail.
يُبلّغ X-FourA-Credits عن العمل المنجز، حتى عند حدوث فشل. تحتسب الفوترة فقط success، لذلك لا يتم فرض رسوم على أي من الحالات الفاشلة المذكورة أعلاه.
النجاح يعتمد على 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 وتتم فوترتها كـ request واحد. بينما تُحتسب استجابة 500 كـ application_fail ولا تتم فوترتها.
ينطبق نفس المنطق على validate.headers وvalidate.data. أي استجابة يقبلها المحرك وفقاً لقواعدك تعود كـ success بغض النظر عن حالة HTTP.
هناك استجابة واحدة لا تكون أبداً success، مع أو بدون validate: استجابة HTTP 200 يحتوي نصها على صفحة فحص برمجيات روبوت يتعرف عليها FourA، مثل مهمة تحقق مرئي أو صفحة تطلب فقط من المتصفح تشغيل JavaScript، أو صفحة رفض يقدمها الموقع مع رمز HTTP 200. يُعتبر هذا الـ request بمثابة application_error ولا تتم فوترته. يظل الـ body يصلك دون تغيير، ويحدد الـ header من النوع X-FourA-Check-Page الصفحة المعنية.
الآثار المترتبة على الفوترة
| النتيجة | خاضع للفوترة | يُحتسب ضمن الحصة |
|---|---|---|
success |
نعم | نعم |
application_error |
لا | لا |
application_fail |
لا | لا |
client_error |
لا | لا |
rate_limit |
لا | لا |
service_error |
لا | لا |
service_fail |
لا | لا |
تتم فوترة الـ requests التي سلمت البيانات التي طلبتها فقط. أما الإخفاقات من جانب FourA، أو من جانب الهدف، أو من جانبك، فجميعها مجانية.
يتناول الجدول الرصيد (credits). تُحتسب حركة مرور premium بشكل منفصل عنها: أي request حاول استخدام منفذ خروج premium يُحتسب عليه حجم البيانات التي نقلتها تلك المحاولة، أياً كانت النتيجة، نظراً لاستخدام منفذ الخروج في كلتا الحالتين. المحاولة التي كانت لا تزال قيد التشغيل عندما استجاب منفذ خروج آخر يتم إيقافها فوراً، وتُحتسب البيانات التي نقلتها حتى ذلك الحين أيضاً.
حركة المرور القياسية (Standard traffic) لا تتبع النتيجة أيضاً: في الخطط ذات الحد الأقصى لنقل البيانات، تُحتسب حركة المرور لكل request ضمن هذا الحد. أما الـ request الذي يتم رفضه بسبب أحد حدود خطتك نفسها، فلا تُحتسب له أي حركة مرور.
تستخدم الأنفاق نفس المصطلحات
ينتهي النفق عبر منفذ 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 الخاص بك في موجز النشاط مع تسمية النتيجة الخاصة به. تجمع صفحتا المقاييس و نظرة عامة الحقل نفسه لإنشاء المخططات الدائرية والجداول الزمنية.
عند تصفية النشاط حسب النتيجة، يمكنك أيضا التركيز على endpoint واحد (Auto، أو Single، أو Proxy Finder، أو Browser) لمعرفة ما إذا كانت فئة معينة من حالات الفشل خاصة بأحدها. قم بتبديل المنتج في الصفحة إلى 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 تماما. |
مواضيع ذات صلة
- أخطاء API: استجابات الأخطاء على مستوى HTTP
- منفذ Proxy: رموز الحالة التي يصل بها رفض النفق
- معدلات الاستخدام (Rate Limits): ما الذي يُشغّل
rate_limit، والشكلان اللذان يعود بهما - المقاييس: أين ترى تفاصيل النتائج
- سجل النشاط: سجل النتائج لكل request