أخطاء خادم 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");
}
ذو صلة
- خادم MCP، الأدوات الأربع ومخططاتها
- وصفات MCP، مطالبات سير العمل المضمنة مع الخادم
- أخطاء API، نفس الغلاف في طبقة REST API الأساسية
- حدود المعدل (Rate Limits)، حدود الحساب والمنصة خلف
rate_limitedوat_capacity