# أخطاء API

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

كيفية معالجة الأخطاء من FourA API.

## تنسيق استجابة الخطأ

تعيد API كائنات JSON مسطحة لجميع الأخطاء. لا يوجد كائن `error` متداخل. عندما يحتوي الفشل على رمز قابل للقراءة آليًا، فإنه يكون حقلًا من المستوى الأعلى: `reason` عند تجاوز حد الخطة، و`code` عند استدعاء proxy بدون مخرج مؤهل.

```json
{
  "error": "Invalid API key"
}
```

تتضمن بعض الأخطاء حقولاً إضافية مثل `status` أو `service` أو `retryAfter` أو `current` أو `limits` في المستوى الأعلى:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

## تتبع request

يتضمن كل API response (سواء كان ناجحاً أو خطأ) header من نوع `X-FourA-Request-Id` مع UUID خاص بتلك المكالمة، باستثناء body لا يمكن لـ FourA قراءته على الإطلاق (JSON غير صالح، أو body يتجاوز 100 KB)، حيث يتم رفضه قبل تعيين ID. سجله في سجلاتك. إذا كنت بحاجة إلى الاستفسار من الدعم عما حدث لـ request معين، فإن هذا الـ ID يتيح لنا العثور عليه.

```bash
curl -i -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://example.com"}'
# HTTP/1.1 200 OK
# X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
# Content-Type: application/json
# ...
```

## أنواع الأخطاء

### 400: طلب غير صالح (Bad Request)

يفتقر نص request إلى حقول مطلوبة، أو يحتوي على قيم غير صالحة، أو يحدد وجهة ترفض API جلبها.

النص الذي لا يكون كائن أو مصفوفة JSON يُعد بتنسيق JSON غير صالح ويحصل على `Invalid JSON in request body`، كما هو موضح أدناه.

في Single وProxy Finder وBrowser، يُذكر الحقل المفقود، أو ذو النوع غير الصحيح، أو الخارج عن النطاق المسموح به في الرسالة على أنه `<field>: <reason>`. يتم ربط الحقول المتداخلة بنقاط (`validate.status.accept`). يتم سرد ما يصل إلى خمس مشكلات مفصولة بـ `; `، وأي شيء يتجاوز ذلك ينهي الرسالة بـ `and <n> more`:

```json
{
  "error": "Invalid request: url: Invalid input: expected string, received undefined"
}
```

إنه `client_error` ولا يتم احتساب تكلفة عليه. يقوم Auto بالإبلاغ عن حقل لا يمكنه قبوله ضمن استجابة HTTP 200 بدلاً من ذلك، كما هو موضح في قسم قراءة حالات الفشل من `/api/auto/` أدناه.

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

```json
{
  "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."
}
```

`<target>` هو العنوان، أو اسم المضيف والعنوان الذي تم تحليله إليه. أي URL يتعذر تحليله، أو لا يكون `http://` أو `https://`، يتلقى رمز الحالة 400 نفسه.

أي هدف على مضيف API التابع لـ FourA نفسه (`eu.api.foura.ai` أو `api.foura.ai`) يتلقى رمز 400 أيضا، وذلك في Single و Proxy Finder و Browser و Auto، قبل جلب أي شيء أو احتساب أي تكلفة. ويعني ذلك عادة أن رابطا تم أخذه من صفحة قد تم تحليله بالاستناد إلى URL الخاص بـ API بدلا من URL الخاص بالصفحة نفسها:

```json
{
  "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL."
}
```

`<url>` هو الهدف تماما كما أرسلته. صفحة [Inspect](https://foura.ai/docs/api/inspect) هي الاستثناء الوحيد: لا يزال FourA يجلب `https://eu.api.foura.ai/inspect` نيابة عنك.

يتلقى أي URL يحتوي على مسافة أو حرف تحكم بداخله رمز الحالة 400 أيضا، في Single وProxy Finder وAuto، قبل جلب أي شيء أو احتساب أي تكلفة. غالبا ما يحمل الرابط المنسوخ من الصفحة كما هو مكتوب أحد هذه الأحرف (`javascript: void(0)`، رابط مشاركة يحتوي على مسافات في نصه). قم بترميزه، بحيث تصبح المسافة `%20`. يجلب Browser مثل هذا الـ URL بالطريقة التي يتبعها Chrome:

```json
{
  "error": "invalid URL: it contains a space; encode it as %20 (the URL as sent: \"https://example.com/a b\")"
}
```

اسم المضيف الذي يتعذر البحث عنه لا يُرفض. يعود الاستدعاء برمز HTTP 200 مع `status: 0` والسبب (`could not resolve <host>: <reason>`)، ولا تتم فوترته. الهدف الذي يتصل به FourA ولكن لا يتلقى منه أي استجابة HTTP (تجاوز حد إعادة التوجيه، أو انتهاء مهلة الاتصال أو القراءة، أو إعادة التعيين) يعود أيضًا برمز HTTP 200، مع `error` و `total_time` وبدون `status`: راجع [Request Outcomes](https://foura.ai/docs/api/outcomes#what-a-failed-call-looks-like).

في Single، يتوقف أي response body يتجاوز 128 ميغابايت بعد فك الترميز عند هذا الحد. يعود الاستدعاء برمز HTTP 200 مع `"error": "Response body exceeds the 128 MB limit"` ولا تتم فوترته.

يتم رفض الـ JSON المشوه في الـ body بالطريقة نفسها، قبل قراءة أي حقل:

```json
{
  "error": "Invalid JSON in request body"
}
```

يمتلك الحقلان `proxy` و `ignoreProxies` رموز الخطأ 400 الخاصة بهما. يقبل كلاهما معرّفات proxy المبهمة التي أرجعتها استجابات سابقة، لذا سيفشل فك تشفير أي قيمة أخرى:

| الرسالة | ما حدث |
|---------|---------------|
| `Invalid proxy format` | القيمة `proxy` ليست معرّف proxy صادر عن FourA. عنوان proxy الأولي يؤدي إلى هذا الخطأ. |
| `Invalid ignoreProxies format` | أحد الإدخالات في `ignoreProxies` ليس معرّف proxy. |
| `Proxy not found` | تم فك تشفير المعرّف بنجاح ولكنه لم يعد يشير إلى نقطة خروج نشطة. اختر معرّفاً جديداً. |
| `Managed exit: this proxy id cannot be pinned to a request` | نقطة الخروج حقيقية، لكنها ليست نقطة ستبقيها FourA مفتوحة لطلب مسمى. معرّف نقطة الخروج المميزة (premium) يؤدي إلى هنا عندما تنفد حركة المرور المميزة المتاحة في خطتك. أعد استخدام الجلسة التي تم استلامه من خلالها، أو نفّذ الاستدعاء عبر `POST /api/proxy/` واستخدم أي نقطة خروج يحددها. |

**الحل:** تحقق من أن طلبك يتضمن جميع الحقول المطلوبة، وأن عناوين URL تستخدم `http://` أو `https://` مع ترميز أي مسافة كـ `%20`، وأن المضيف يشير إلى عنوان عام، وأن أي قيمة `proxy` هي معرّف منسوخ حرفياً من استجابة سابقة.

هذه نتائج `client_error`: لم يغادر الطلب FourA مطلقاً، لذا لم يتم استهلاك أي رصيد نيابة عنك.

### 401: غير مصرح به (Unauthorized)

مفتاح API مفقود أو غير صالح.

مفتاح مفقود:

```json
{
  "error": "Missing API key. Include X-API-Key header."
}
```

مفتاح غير صالح:

```json
{
  "error": "Invalid API key"
}
```

**الحل:** تحقق من أن ترCall`X-API-Key` الخاص بك يحتوي على مفتاح صالح. قم بتوليد مفتاح جديد من [لوحة التحكم](https://foura.ai/dashboard) إذا لزم الأمر.

يشير الرمز 401 دائماً إلى أن FourA قد تحقق من مفتاحك ورفضه. عندما يتعذر على FourA التحقق من المفتاح لبضع ثوانٍ، فإنه يُرجع 503 `API key check temporarily unavailable` بدلاً من ذلك (انظر أدناه)، ولا يُرجع 401 مطلقاً.

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

طلب الاستدعاء endpoint أو معاملاً لا تتضمنه خطتك. يحدد الـ response القيمة `X-FourA-Limit` ويضع نفس الرمز في الـ body ضمن `reason`:

```json
{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}
```

تكون قيمة `reason` هي `plan_limit_feature` بالنسبة لنقطة endpoint لا تشملها الخطة أو بالنسبة لـ `exitCountries` وحقول موقع الخروج في خطة بدون استهداف جغرافي، وتكون `plan_limit_premium` بالنسبة لـ `exitClass: premium` في خطة بدون مواقع خروج مميزة، أو بالنسبة لـ [موقع خروج](https://foura.ai/docs/api/endpoints#exit-location) لم يتبق له حركة مرور مميزة. تحدد السلسلة النصية `error` اسم الـ endpoint أو المعامل.

رمز 403 من FourA لا يتعلق أبدا بالموقع المستهدف: لم يتم الاتصال بالهدف إطلاقا. وأي رمز 403 يعيده الموقع المستهدف يصل في هيئة HTTP 200 مع وجود `status: 403` داخل الـ body.

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

### 413: حمولة الطلب كبيرة جدا

حجم الـ body الخاص بطلب JSON أكبر مما يقبله FourA (100 كيلوبايت). الرد ليس بصيغة JSON ولا يحمل `X-FourA-Request-Id`، لأن الـ body يُرفض قبل قراءته.

**الحل:** أرسل حمولة `data` بحجم أصغر. لم يتم استهلاك أي رصيد.

### 429: تم تجاوز معدل الطلبات

هناك فحصان مختلفان يردان برمز 429، ولا يحملان الحقول نفسها.

**حدود خطتك الخاصة.** يحدد الرد ترويسة `X-FourA-Limit` توضح الحد الذي رفض الطلب، ويضع الرمز نفسه في الـ body ضمن `reason`:

```json
{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}
```

`reason` هي واحدة من `plan_limit_concurrency` أو `plan_limit_rate` أو `plan_limit_browser_daily` أو `plan_limit_credits` أو `plan_limit_bandwidth`. عندما يفيد الانتظار، تكون مدة الانتظار موجودة في `retry_after_seconds` وفي header `Retry-After`، ولا توجد إطلاقاً في `retryAfter`. لا يتضمن `plan_limit_browser_daily` أي منهما، لأن الحصة تعود عند منتصف الليل بالتوقيت العالمي المنسق (UTC) وليس بالثواني. لم يتم استهلاك أي شيء: النتيجة هي `rate_limit`، وتتم فوترة `success` فقط.

**الحصة المشتركة للمنصة.** لا يوجد header `X-FourA-Limit`، والانتظار موجود في `retryAfter`:

```json
{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": { "concurrency": 12, "rpm": 3000 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`current` و `limits` يصفان الخدمة عبر جميع حركات المرور، وليس حسابك فقط. الرفض هنا يعني أن FourA مشغول.

**الحل:** انتظر أياً كان ما يحمله الـ response من `Retry-After` أو `retry_after_seconds` أو `retryAfter`. عند الوصول إلى حد التزامن أو الـ rate limit، حدد سقفاً لعدد الـ requests المفتوحة بدلاً من إعادة إرسال الدفعة المرفوضة. عند الوصول إلى الحد اليومي أو حد فترة الفوترة، أوقف التشغيل. راجع [Rate Limits](https://foura.ai/docs/api/rate-limits) لكل حقل و [تشغيل الـ Requests بالتوازي](https://foura.ai/docs/how-to/run-requests-in-parallel) لمعرفة النمط.

### 500: خطأ في الخادم

حدث خطأ ما من جانبنا.

**الحل:** أعد محاولة الـ request بعد تأخير قصير. إذا استمر الخطأ، فتحقق من [صفحة الحالة](https://updates.foura.ai/status) أو تواصل مع الدعم الفني مزوداً بـ `X-FourA-Request-Id` من الـ response الفاشل.

### 502: المصدر الأساسي غير متاح

لم يتمكن FourA من الحصول على استجابة من محركه الخاص (`Upstream unavailable`: فشل الاتصال)، أو تلقى استجابة لم يتمكن من قراءتها (`Malformed JSON from backend`).

```json
{
  "error": "Upstream unavailable",
  "details": "..."
}
```

**الحل:** أعد المحاولة مع فترة تراجع قصيرة (backoff). هذا الخطأ من جانبنا، لذا لن يكلفك أي شيء: النتيجة هي `service_error` ولا يتم تحصيل الرسوم إلا مقابل `success`.

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

لم ينته المحرك من المعالجة ضمن الميزانية الزمنية المحددة لهذا الطلب (request).

```json
{
  "error": "Upstream timeout",
  "details": "the backend did not finish inside the time budget for this request"
}
```

يرتبط الخطأ 504 بالمدة التي استغرقها تنفيذ العمل، وليس بمفتاحك، أو معلماتك، أو الـ proxy الخاص بك. الأهداف البطيئة، وحل التحديات للمرة الأولى (cold challenge solves)، والصفحات الكبيرة هي الأسباب المعتادة.

**الحل:** ارفع قيمة `timeout_ms` في الـ request (يقبل Single حتى 120000، و Browser حتى 120000، و Auto حتى 180000)، أو أعد المحاولة. ينتظر FourA المهلة الزمنية التي حددتها بالإضافة إلى هامش صغير، لذا فإن طلب المزيد من الوقت يمنحك فعليا وقتا إضافيا.

### 503: الخدمة معطلة أو بلغت السعة القصوى

يعني الخطأ 503 إما أن الخدمة غير متاحة مؤقتا للصيانة أو أن الحد المسموح به للعمليات المتزامنة (concurrency) على المنصة قد اكتمل. يحمل كلا النموذجين المفاتيح نفسها: `error`، و `status`، و `service`، و `retryAfter`، و `current`، و `limits`. ميز بينهما من خلال سلسلة `error`، وليس بناء على الحقول الموجودة.

```json
{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}
```

`Service disabled` تعني وجود صيانة، بينما تُظهر `current` القيمة `0` لكلا العدادين، لأن الطلب رُفض قبل قياس أي شيء. `Service at capacity` هي صيغة التزامن، وهناك تُظهر `current` الاستخدام الفعلي للمنصة. راجع [Rate Limits](https://foura.ai/docs/api/rate-limits) للاطلاع على هذا الهيكل.

**الحل:** انتظر `retryAfter` ثوانٍ، ثم أعد المحاولة. تعرض صفحة الحالة فترات الصيانة النشطة.

هناك شكل ثالث لخطأ 503 لا يحتوي على `retryAfter`. وهو يعني أن المحرك المسؤول عن الـ endpoint لم يتمكن من معالجة طلبك: إما لأنه كان قيد إعادة التشغيل، أو تعطل من جانب FourA قبل تشغيل طلبك، أو (في Browser) ظلت جميع المتصفحات مشغولة طوال فترة الـ 10 ثوانٍ التي تنتظرها الصفحة لتوفر أحدها. تمثل `backend_status` حالة المحرك نفسه وتُمثل `detail` بداية استجابته:

```json
{
  "error": "Backend service unavailable",
  "backend_status": 503,
  "detail": "..."
}
```

إنه `service_error` ولا يتم احتساب تكلفته. أعد المحاولة بعد ثانية أو ثانيتين. أي request غير صالح بطبيعته لن ينتهي به الأمر هنا مطلقا: حيث يتلقى رمز 400 يحدد اسم الحقل.

رمز 503 الرابع يعني أن FourA تعذر عليه التحقق من API key الخاص بك للحظة، على سبيل المثال أثناء تبديل قاعدة البيانات الخاصة به. لا توجد مشكلة في المفتاح الخاص بك ولم يتم تشغيل أي شيء. يحمل هذا الرمز `Retry-After: 5` وفترة الانتظار نفسها في `retryAfter`:

```json
{
  "error": "API key check temporarily unavailable",
  "status": 503,
  "retryAfter": 5
}
```

لا يتم احتساب التكلفة. أعد المحاولة بعد `retryAfter` ثوانٍ. المفتاح الذي أكده FourA خلال آخر 10 دقائق يستمر في العمل أثناء مثل هذه الحالات، لذلك تعد هذه الإجابة نادرة.

## قراءة حالات الفشل من `/api/auto/`

يجيب `POST /api/auto/` برمز HTTP 200 عندما يتم تشغيل ladder، حتى لو فشلت كل خطوة (rung). النتيجة الفعلية موجودة داخل الـ body:

```json
{
  "status": 403,
  "error": "exit blocked by the target defense",
  "attempts": 7,
  "meta": { "rung": "fail", "solved": false, "attempts": 7, "credits": 47 }
}
```

`status` هي آخر حالة استجاب بها الهدف، أو 502 عندما لا تصل أي محاولة إليه (504 عندما تنفد المهلة الزمنية المحددة أولاً). تحمل كل استجابة فاشلة من ladder تم تشغيله أيضاً `attemptReport` يحصي ما واجهته المحاولات، مع `summary` من سطر واحد آمن للتسجيل في السجلات، ويوضح `meta.attemptsByEngine` و`meta.browserRequests` ما أرسله الاستدعاء. راجع [لماذا فشل استدعاء Auto](https://foura.ai/docs/guides/smart-fetch#why-an-auto-call-failed). يتم إرجاع أي حقل في الطلب لا يمكن لـ Auto قبوله (مثل `timeout_ms` أقل من 5000 أو أكثر من 180000) بالطريقة نفسها: HTTP 200 مع `"status": 400` والسبب في `error`، وذلك قبل إجراء أي محاولة وبدون أي تكلفة.

لذلك لا تقم بالتفريع البرمجي بناءً على حالة النقل لـ Auto. اقرأ `status` و`error` من نص الاستجابة بدلاً من ذلك. تعني استجابة non-200 فعلية من `/api/auto/` أن FourA رفض الاستدعاء قبل بدء ladder، أو لم يتمكن من إكماله: 400 (تنسيق JSON غير صالح، أو هدف خاص أو محجوز، أو هدف على مضيف API التابع لـ FourA نفسه)، أو 401، أو 413، أو 502، أو 503، أو 504. يتم الرد على أحد قيود الخطة مباشرة عند المدخل: يتلقى `exitClass: premium` على خطة بدون مخارج premium رمز 403 مع `X-FourA-Limit: plan_limit_premium`، قبل تنفيذ أي عمل. كل القيود الأخرى، سواء كانت خاصة بك أو بالمنصة، تُعاد داخل 200 مع بيان حالتها في نص الاستجابة.

عندما يفشل موقع في عدة استدعاءات Auto متتالية تم إجراؤها باستخدام مفتاح API الخاص بك، يستجيب Auto للاستدعاءات التالية من هذا المفتاح فوراً لفترة دون محاولة: `"error": "target temporarily unservable, retry later"` و`"status": 503` و`retryAfter` بالثواني. هذا لا يستهلك أي تكلفة؛ انتظر `retryAfter` ثوانٍ.

كما أن حد الخطة الذي يواجهه أحد الاستدعاءات الفرعية يُعاد أيضاً كـ HTTP 200. نص الاستجابة هو الرفض نفسه، مع `reason` الخاص به، بالإضافة إلى `status` و`meta`، وتحمل الاستجابة نفس `X-FourA-Limit` header كرفض مباشر:

```json
{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

الحدود التي توقف السلم وتلك التي تغلق درجة واحدة فقط مشروحة في [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch#when-your-plans-limits-meet-the-ladder).

## إخفاقات جهة الهدف ضمن 200 OK

لا يظهر كل إخفاق كحالة HTTP غير 2xx. عندما يرد الهدف بـ HTTP 200 ولكن إجابة FourA تتضمن `error` (رفضت قواعد `validate` الخاصة بك الـ body، على سبيل المثال) أو كان الـ body عبارة عن صفحة تحقق يتعرف عليها FourA، فإن النتيجة تكون `application_error`. عندما يعيد الهدف حالة أخرى غير 200 لا تقبلها قواعد `validate` الخاصة بك، تكون النتيجة `application_fail` ويمر الـ body دون تغيير.

لا تتم فوترة أي من الحالتين: تتم فوترة `success` فقط. ينتظر استدعاء Browser الذي يجد كل المتصفحات مشغولة لمدة تصل إلى 10 ثوانٍ حتى يصبح أحدها متاحا. وإذا لم يتح أي منها، فإنه يعود كرمز 503 `Backend service unavailable` الموضح أعلاه. يمكن لـ Browser أيضا الرد بـ HTTP 200 مع `"error": "No available browser slot"` عندما يتعذر عليه الحصول على متصفح على الإطلاق. لا تتم فوترة أي منهما. أعد المحاولة بعد بضع ثوانٍ، أو قلل عدد استدعاءات Browser المفتوحة في وقت واحد. يغطي مرجع [Outcomes](https://foura.ai/docs/api/outcomes) التصنيف الكامل.

يمكن لاستدعاء Single عبر `proxy` قمت بتثبيته أن يرد أيضا بـ HTTP 200 مع `"error": "The exit gave the same answer for <n> different sites"` بجانب الـ body. لاحظ FourA أن منفذ الخروج هذا يقدم نفس الصفحة لمواقع غير ذات صلة، وبالتالي فإن الصفحة خاصة بمنفذ الخروج نفسه، وليست الصفحة التي طلبتها. حالتها هي `application_error` ولا تتم فوترتها. احصل على منفذ خروج جديد من `POST /api/proxy/`، والذي يتجاوز مثل هذا المنفذ تلقائيا.

ينطبق الأمر نفسه عندما ترد شبكة منفذ الخروج الخاصة بدلا من الموقع. يعود الاستدعاء مع `"error": "The exit answered instead of the site (<name>)"` أو `"error": "Corporate web gateway intercepted the request (<name>)"` (صفحة تسجيل دخول أو تصفية، أو إعادة توجيه إلى إحداهما)، ومع `"error": "The exit intercepted TLS and answered instead of the site (<name>)"` عندما يرد منفذ الخروج نيابة عن الموقع نفسه، أو مع `"error": "Honeypot echo proxy (plaintext request dump)"` عندما يرسل منفذ الخروج نسخة من الـ request الخاص بك. يتحقق FourA من هذه الحالات أيا كانت قواعد `validate` لديك، بما في ذلك تنزيلات `returnBuffer`. لا تتم فوترة أي منها. احصل على منفذ خروج جديد بالطريقة نفسها.

## ترميز الاستجابة

يقوم FourA بفك ترميز نصوص الـ response تلقائيا إلى UTF-8. إذا كان الهدف يقدم `windows-1251` أو `gbk` أو `shift_jis` أو `iso-8859-*`، أو أي charset أخرى معلنة في header الـ `Content-Type` أو وسم HTML `<meta charset>`، فستتلقى سلسلة UTF-8 سليمة في حقل `data` (في Single وProxy) أو `body` (في Browser).

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

## استراتيجية إعادة المحاولة

سياسة إعادة محاولة عملية:

```python
import time
import requests

# Plan limits that no short wait will clear: stop the run instead of retrying.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def make_request(url, payload, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            url,
            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
            json=payload,
        )
        if resp.status_code == 200:
            return resp.json()

        body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
        request_id = resp.headers.get("X-FourA-Request-Id", "?")

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"{limit} (request {request_id}): {body.get('error')}")

        # Plan limits send Retry-After and retry_after_seconds; platform limits send retryAfter.
        header = resp.headers.get("Retry-After")
        retry_after = (
            int(header) if header and header.isdigit()
            else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt
        )

        if resp.status_code in (429, 503):
            time.sleep(retry_after)
            continue
        if resp.status_code >= 500:   # 500, 502, 503, 504 are all ours to fix
            time.sleep(2 ** attempt)
            continue

        # 400/401/403/404 won't fix themselves
        raise RuntimeError(f"{resp.status_code} (request {request_id}): {body.get('error')}")

    raise RuntimeError(f"Exhausted {max_retries} retries")
```

## إخفاقات الـ Proxy تحمل تقريرًا

أي استدعاء `POST /api/proxy/` يستنفد المحاولات يعود برمز HTTP 200 مع غلاف خطأ (error envelope)، وليس برمز خطأ HTTP. نص الخطأ قصير وله دائمًا نفس التنسيق، لذا يرافقه كائن `attemptReport` يتضمن أعداد المحاولات:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

سجّل `attemptReport.summary` إلى جانب الخطأ وستعرف ما إذا كانت نقاط الخروج محظورة، أو معطلة، أو تعيد صفحات رفضتها قواعد `validate` الخاصة بك. مرجع الحقول وما يجب فعله حيال كل عدد: [أسباب استنفاد محاولات طلب Proxy](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

## ذات صلة

- [Rate Limits](https://foura.ai/docs/api/rate-limits): حدود الخطة، والتزامن، وتفاصيل RPM
- [تشغيل الطلبات بالتوازي](https://foura.ai/docs/how-to/run-requests-in-parallel): البقاء ضمن حد التزامن لخطتك
- [نتائج الطلبات](https://foura.ai/docs/api/outcomes): شرح قيم النتائج السبع
- [مشكلات شائعة](https://foura.ai/docs/troubleshooting/common-issues): الأعراض، والأسباب، والحلول
- [فحوصات الموقع](https://foura.ai/docs/api/site-checks): عندما يكون المحتوى صفحة تحدٍ بدلا من خطأ
- [أسباب استنفاد محاولات طلب Proxy](https://foura.ai/docs/troubleshooting/proxy-attempt-report): قراءة `attemptReport`
