# أخطاء خادم MCP

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

كيفية معالجة الأخطاء التي يرجعها [foura-mcp server](https://foura.ai/docs/mcp/server).

تكون كل استجابة خطأ من أي من الأدوات الأربع (`foura_auto`، و`foura_single`، و`foura_proxy`، و`foura_browser`) مهيكلة. يمكن لوكلاء LLM قراءة حقل `code` لمنطق إعادة المحاولة دون تحليل النص النثري.

## شكل الغلاف

يحمل كل خطأ (`isError: true`) كتلة `structuredContent`. الحد الأدنى من الحقول في كل خطأ:

```json
{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}
```

في أخطاء المصدر مع حالة HTTP، يتوفر `status` أيضًا. عندما ترفض الحصة المشتركة للمنصة طلبًا ما، يضيف الغلاف `retryAfter` و`current.{concurrency, rpm}` و`limits.{maxConcurrency, maxRpm}`، بنفس بنية [أخطاء REST API](https://foura.ai/docs/api/errors) الأساسية.

عندما يرفض أحد حدود خطتك الخاصة طلبًا، يكون الكود هو ذلك الحد: `plan_limit_` متبوعًا بـ `credits` أو `bandwidth` أو `rate` أو `concurrency` أو `browser_daily` أو `premium` أو `feature`. يحمل `retryAfter` فترة الانتظار عندما يؤدي الانتظار إلى حل المشكلة، ويكون غائبًا عند الوصول إلى حد لا يمكن للانتظار حله، مثل ميزة لا تتضمنها الخطة. ولا يحمل `plan_limit_browser_daily` أي `retryAfter` أيضًا: فهو يُعاد ضبطه عند منتصف الليل بتوقيت UTC. يحدد `plan_limit_credits` و`plan_limit_bandwidth` الحد الأقصى لـ `retryAfter` بـ 24 ساعة ويضيفان `resets_at`، وهو وقت انتهاء فترة الفوترة بدقة، لذا اقرأ `resets_at` قبل جدولة إعادة المحاولة.

في `foura_auto`، يُرجع الحد الخاص بالخطة عند استيفائه داخل مساره كـ `rate_limited` أو `forbidden`، مع وجود كود الخطة في `reason`.

## قيم `code` الثابتة

| الكود | HTTP | المعنى | هل إعادة المحاولة آمنة؟ |
|---|---|---|---|
| `ssrf_blocked` | لا ينطبق | الهدف هو عنوان خاص أو محجوز (RFC 5735، أو RFC 6598، أو IPv6 المحجوز)، أو أن الـ URL ليس http(s)، أو تعذر حل اسم المضيف | لا، تحقق من الـ URL. يمكن إعادة محاولة البحث الذي فشل مؤقتا |
| `upstream_non_json` | متغير | أعاد المصدر الأساسي جسما لم يكن بتنسيق JSON صالح | ربما، تحقق من الأمر |
| `output_validation_failed` | لا ينطبق | رفض `outputSchema` الخاص بخادم MCP استجابة المصدر الأساسي، أو تعذر على الأداة إكمال الاستدعاء بالكامل (لم يتم تكوين مفتاح API، أو تعذر الوصول إلى الـ API) | ربما: تحقق من الإعداد، ثم أبلغ عن المشكلة |
| `bad_request` | 400 | رُفض هيكل المدخلات بواسطة FourA API، أو يشير الـ URL الهدف إلى API الخاص بـ FourA بدلا من صفحة (يمكن جلب `/inspect` فقط هناك)، أو يحتوي الـ URL على مسافة غير مشفرة بداخله (قم بترميزها كـ `%20`)، أو يحدد `proxy` مخرجا لا يمكن للاستدعاء استخدامه: مخرج premium بعد استنفاد حركة مرور premium الخاصة بك يستجيب بـ `Managed exit: this proxy id cannot be pinned to a request`. لا يتم جلب أي شيء أو فرض رسوم | لا، أصلح المعاملات |
| `auth_failed` | 401 | مفتاح FourA API مفقود أو غير صالح أو معطل؛ لا يتعلق هذا ببيانات اعتماد الموقع الهدف | لا، أصلح مفتاح FourA |
| `forbidden` | 403 | استجاب الهدف بالرمز 403 ورفضه `validate` الخاص بك (فحص موقع، قيود دولة) | لا، أو انتقل إلى `foura_proxy` |
| `not_found` | 404 | الـ URL أو الـ endpoint الهدف غير موجود | لا |
| `rate_limited` | 429 | الحصة المشتركة للمنصة في الدقيقة، أو استجابة 429 من الهدف رفضها `validate` الخاص بك. في `foura_auto` يمكن أن يرجع ذلك أيضا إلى رصيد خطتك أو حركة المرور أو الـ rate limit (راجع `reason`) | نعم، انتظر `retryAfter` عند توفره، وإلا فاستخدم التراجع التدريجي |
| `at_capacity` | 503 | تم الوصول إلى الحد الأقصى للتزامن (`current.concurrency` > `limits.maxConcurrency`)، أو تم إيقاف الخدمة للصيانة (`error` يقرأ `Service disabled`، و`retryAfter` هو 60) | نعم، انتظر `retryAfter` ثانية |
| `service_disabled` | 503 | محجوز. الخدمة المعطلة للصيانة تظهر اليوم كـ `at_capacity`، والأداة التي لا تتضمنها خطتك تظهر كـ `plan_limit_feature` | اتصل بالدعم |
| `service_unavailable` | 503 | خطأ 503 عام من المصدر الأساسي | نعم، تراجع تدريجي قصير |
| `upstream_error` | 500+ أو 0 | استجاب الهدف بخطأ في الخادم، أو في `foura_proxy`، لم يستجب `foura_browser` و`foura_auto` مطلقا | نعم، تراجع تدريجي أسي |
| `upstream_client_error` | 4xx | أخطاء 4xx أخرى لم يتم تغطيتها أعلاه | عادة لا |
| `upstream_unknown` | أخرى | تم تشغيل الطلب ولكنه لم ينتج عنه استجابة مقبولة: في `foura_single` لم يستجب الهدف مطلقا (مهلة، رفض الاتصال)، وفي أي أداة رفض `validate` الخاص بك استجابة 2xx أو 3xx. اقرأ `status` و`error` | تحقق من الأمر |
| `no_eligible_proxy` | لا ينطبق | لا يوجد proxy يطابق قائمة `exitCountries` المسموح بها الصارمة؛ يحتوي `details.exitCountries` على النطاق القياسي | أعد المحاولة لاحقا؛ لا تغير النطاق إلا بشكل صريح |
| `plan_limit_credits` | 429 | تم استنفاد الرصيد الشهري في خطتك | نعم، بعد `retryAfter`، أو قم بتغيير الخطة |
| `plan_limit_bandwidth` | 429 | تم استنفاد حصة حركة المرور في خطتك لفترة الفاتورة الحالية | نعم، بعد `retryAfter`، أو قم بتغيير الخطة |
| `plan_limit_rate` | 429 | تجاوز عدد الطلبات في الدقيقة لـ endpoint هذا ضمن خطتك | نعم، بعد `retryAfter` |
| `plan_limit_concurrency` | 429 | تجاوز عدد الطلبات المتزامنة لـ endpoint هذا ضمن خطتك | نعم، بعد `retryAfter` |
| `plan_limit_browser_daily` | 429 | تم استنفاد حصة Browser اليومية في خطتك | نعم، غدا، أو استخدم `foura_single` / `foura_proxy` |
| `plan_limit_premium` | 403 | أرسلت `exitClass: "premium"` على خطة لا تتضمن مخارج premium | لا، احذف المعامل أو قم بتغيير الخطة |
| `plan_limit_feature` | 403 | الخطة لا تدعم ذلك الـ endpoint أو تلك الميزة | لا، قم بتغيير الخطة |

## أخطاء مستوى HTTP من خادم MCP

تحدث بعض حالات الفشل عند طبقة نقل MCP، قبل استدعاء أي أداة. تُرجع هذه الحالات أخطاء JSON-RPC خام (بدون `structuredContent`):

| HTTP | متى | ما تراه |
|---|---|---|
| 400 | header غير مدعوم من نوع `MCP-Protocol-Version` | `Unsupported MCP-Protocol-Version: <value>. Supported (from @modelcontextprotocol/sdk): 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07. Upgrade foura-mcp's SDK pin to extend.` |
| 401 | استدعاء أداة أو قراءة مورد بدون API key. يعمل سرد الأدوات والمطالبات بدون مفتاح | خطأ JSON-RPC + `WWW-Authenticate: Bearer realm="foura-mcp"` |
| 403 | header غير مسموح به من نوع `Origin` أو `Host` (حماية من DNS-rebinding، CVE-2025-66414) | `Origin <value> is not in the allowlist` أو `Host <value> is not in the allowlist` |
| 405 | `GET` أو `DELETE` على `/mcp` (وضع stateless) | `Method not allowed in stateless mode. Use POST /mcp.` |
| 413 | حجم نص request أكبر من 256 كيلوبايت | الخطأ الافتراضي 413 من Express |

قوائم السماح للرمز 403 قابلة للتهيئة عبر متغيرات البيئة لمن يستضيفون الخادم بأنفسهم من خلال `FOURA_MCP_ALLOWED_HOSTS` و`FOURA_MCP_ALLOWED_ORIGINS`.

## ملفات تعريف المتصفح المرفوضة

ملف تعريف المتصفح الذي يتعذر على الدليل تقديمه، أو ملف التعريف المرسل مع تعيين `unblocker` إلى `false`، يرجع كفشل في المصدر الرئيسي مع ذكر السبب في `error` ولا يغادر request خدمة FourA مطلقًا. بالنسبة لمزيج `browser` و`os` و`version` غير الموجود، تحدد الرسالة ما هو متاح، لذا أعد المحاولة باستخدام أحد التوليفات المدرجة بدلاً من نفس التوليفة. يتلقى معرف `profile` غير المعروف الخطأ `unknown profile` بدون قائمة: ابحث عن المعرف في [`GET /api/profiles`](https://foura.ai/docs/api/endpoints#browser-profiles).

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

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

خمس فئات:

- **خطتك هي التي رفضت الطلب، وليس الموقع المستهدف**: أي رمز `plan_limit_*`. يحتسب كل من `plan_limit_credits` و`plan_limit_bandwidth` على مستوى الحساب بأكمله، لذلك سيتم رفض العمل نفسه عبر أداة أخرى أيضا. ينطبق كل من `plan_limit_rate` و`plan_limit_concurrency` و`plan_limit_browser_daily` و`plan_limit_feature` على endpoint واحد، لذا يمكن لأداة أخرى أن تعمل إذا كانت قادرة على أداء المهمة. انتظر انتهاء `retryAfter` إذا وجد، وإلا فيجب تغيير الخطة. `plan_limit_premium` هو الرمز الذي يمكنك معالجته بنفسك، عن طريق إزالة `exitClass`.
- **انتظر وأعد المحاولة**: `rate_limited`، `at_capacity`، `service_unavailable`، `upstream_error`. التزم بـ `retryAfter` عند توفره. استخدم exponential backoff مع jitter عند غيابه. لا تستجب لذلك بإعادة إرسال جميع استدعاءات الأدوات الموجودة في قائمة الانتظار دفعة واحدة: بل قلل عدد الاستدعاءات المتزامنة بدلا من ذلك.
- **حافظ على النطاق وأعد المحاولة لاحقا**: `no_eligible_proxy`. لا تقم بإزالة `exitCountries` أو استبدال بلد آخر دون إشعار. لا تغير قائمة السماح أو توسعها إلا عندما يغير المستخدم المتطلبات صراحة.
- **لا تعد المحاولة حتى يتم تصحيح المدخلات أو بيانات الاعتماد**: `bad_request`، `auth_failed`، `not_found`، `ssrf_blocked`. بالنسبة لـ `auth_failed`، تحقق من مفتاح FourA API، وليس بيانات اعتماد الموقع المستهدف.
- **بدل الأداة عندما يتطلب المحتوى ذلك**: يمكن لـ `forbidden` على `foura_single` أن يبرر محاولة محدودة عبر `foura_proxy`. استخدم `foura_browser` عندما يتطلب المحتوى المطلوب وجود JavaScript. بعد نجاح اختيار proxy، مرر معرف `proxy` المسترجع إلى `foura_browser.proxy` بدلا من بدء عملية اختيار جديدة.

## مثال على إعادة المحاولة (TypeScript، من جانب MCP)

```typescript
async function callWithRetry(call: () => Promise<any>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await call();
    if (!r.isError) return r;

    const code = r.structuredContent?.code;
    const wait = r.structuredContent?.retryAfter ?? Math.min(2 ** attempt, 30);

    if (["rate_limited", "at_capacity", "service_unavailable", "upstream_error"].includes(code)) {
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    // Non-retryable, surface to caller
    throw new Error(`${code}: ${r.structuredContent?.error}`);
  }
  throw new Error("max retries exceeded");
}
```

## ذو صلة

- [خادم MCP](https://foura.ai/docs/mcp/server)، الأدوات الأربع ومخططاتها
- [وصفات MCP](https://foura.ai/docs/mcp/recipes)، مطالبات سير العمل المضمنة مع الخادم
- [أخطاء API](https://foura.ai/docs/api/errors)، نفس الغلاف في طبقة REST API الأساسية
- [حدود المعدل (Rate Limits)](https://foura.ai/docs/api/rate-limits)، حدود الحساب والمنصة خلف `rate_limited` و `at_capacity`
