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

> URL: https://foura.ai/ar/docs/api/outcomes
> Updated: 2026-11-11
> Index: https://foura.ai/llms.txt

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

فقط `success` يستهلك الرصيد. يتم احتساب حركة المرور المتميزة (Premium) بمعزل عن الرصيد ولا تتبع النتيجة: راجع [الآثار المترتبة على الفوترة](#billing-implications).

## النتائج السبع

هذه هي النتائج السبع التي يمكن أن ينتهي إليها أي request. يستخدم النفق خمس نتائج منها: راجع [الأنفاق تستخدم نفس المفردات](#tunnels-use-the-same-vocabulary) أدناه.

| النتيجة | الطبقة | المعنى |
|---------|-------|--------------|
| `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** تقع مسؤوليتها علينا. أعد المحاولة، وتحقق من [صفحة الحالة](https://updates.foura.ai/status) إذا استمرت المشكلة.

الموقع المستهدف الذي يُرجع `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` |

حلقة إعادة توجيه، كما يراها الصف الخامس:

```json
{
  "error": "Number of redirects hit maximum amount",
  "total_time": 0.808
}
```

في `POST /api/proxy/`، يحمل الاستدعاء الذي يستنفد المحاولات `error: Download maxTry limit reached` و`attemptReport` مع التعدادات (انظر [API Errors](https://foura.ai/docs/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`. وسيصلك نص الاستجابة دون أي تغيير.

```bash
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`](https://foura.ai/docs/api/response-headers) الصفحة المعنية.

## الآثار المترتبة على الفوترة

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

تتم فوترة الـ requests التي سلمت البيانات التي طلبتها فقط. أما الإخفاقات من جانب FourA، أو من جانب الهدف، أو من جانبك، فجميعها مجانية.

يتناول الجدول الرصيد (credits). تُحتسب حركة مرور premium بشكل منفصل عنها: أي request حاول استخدام [منفذ خروج premium](https://foura.ai/docs/api/endpoints#exitclass) يُحتسب عليه حجم البيانات التي نقلتها تلك المحاولة، أياً كانت النتيجة، نظراً لاستخدام منفذ الخروج في كلتا الحالتين. المحاولة التي كانت لا تزال قيد التشغيل عندما استجاب منفذ خروج آخر يتم إيقافها فوراً، وتُحتسب البيانات التي نقلتها حتى ذلك الحين أيضاً.

حركة المرور القياسية (Standard traffic) لا تتبع النتيجة أيضاً: في الخطط ذات الحد الأقصى لنقل البيانات، تُحتسب حركة المرور لكل request ضمن هذا الحد. أما الـ request الذي يتم رفضه بسبب أحد حدود خطتك نفسها، فلا تُحتسب له أي حركة مرور.

## تستخدم الأنفاق نفس المصطلحات

ينتهي النفق عبر [منفذ proxy](https://foura.ai/docs/api/proxy-port) بإحدى هذه النتائج أيضاً، لذا تغطي مجموعة واحدة من التسميات كلا المنتجين. يمكن أن تحدث خمس نتائج فقط من أصل سبع، لأن نتيجتي `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 ليتم احتساب تكلفة عليه. يقيس المنفذ البايتات بدلا من ذلك. راجع [كيف تتم محاسبة خطتك](https://foura.ai/docs/guides/plans-and-metering).

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

يظهر كل request يجريه مفتاح API الخاص بك في موجز [النشاط](https://foura.ai/docs/dashboard/activity-log) مع تسمية النتيجة الخاصة به. تجمع صفحتا [المقاييس](https://foura.ai/docs/dashboard/metrics) و [نظرة عامة](https://foura.ai/docs/dashboard/overview) الحقل نفسه لإنشاء المخططات الدائرية والجداول الزمنية.

عند تصفية النشاط حسب النتيجة، يمكنك أيضا التركيز على 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](https://foura.ai/docs/api/errors): استجابات الأخطاء على مستوى HTTP
- [منفذ Proxy](https://foura.ai/docs/api/proxy-port): رموز الحالة التي يصل بها رفض النفق
- [معدلات الاستخدام (Rate Limits)](https://foura.ai/docs/api/rate-limits): ما الذي يُشغّل `rate_limit`، والشكلان اللذان يعود بهما
- [المقاييس](https://foura.ai/docs/dashboard/metrics): أين ترى تفاصيل النتائج
- [سجل النشاط](https://foura.ai/docs/dashboard/activity-log): سجل النتائج لكل request
