أخطاء خادم MCP

كيفية معالجة الأخطاء التي يرجعها foura-mcp server.

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

شكل الغلاف

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

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

في أخطاء المصدر مع حالة HTTP، يتوفر status أيضًا. عندما ترفض الحصة المشتركة للمنصة طلبًا ما، يضيف الغلاف retryAfter وcurrent.{concurrency, rpm} وlimits.{maxConcurrency, maxRpm}، بنفس بنية أخطاء REST API الأساسية.

عندما يرفض أحد حدود خطتك الخاصة طلبًا، يكون الكود هو ذلك الحد: 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.

هذه حالات رفض وليست انقطاعات: لا يمكن أن تنجح إعادة محاولة 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)

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");
}
آخر تحديث: 13 نوفمبر 2026