الانتقال إلى المحتوى الرئيسي
عندما يوقف حاجز حماية أو جدار الحماية طلباً، يعيد OrcaRouter خطأً مُصنّفاً يمكن لكودك التفرّع بناءً عليه — وليس 400 غامضاً. ثلاثة رموز أمان تغطي الحالات التي ستراها: مطالبة أو استجابة مفحوصة، واستدعاء أداة مرفوض، واستدعاء أداة مُعلَّق لموافقة بشرية. هذه الصفحة هي مرجع تلك الرموز — حالة الاستخدام لكلٍّ منها، وحالة HTTP بالضبط، وما يكلّفك، والقاعدة الأهم: منطق إعادة المحاولة يجب أن يعاملها كحالة خاصة. الثلاثة جميعاً معلَّمة skip-retry؛ إعادة تشغيل نفس الاستدعاء بلا تفكير تطلق نفس التحكّم مجدداً فحسب.
هذه رموز فرض — البوابة تقرر عدم تمرير استدعائك. وهي متمايزة عن أخطاء المزود الأعلى (429 من نموذج، تجاوز سياق) وعن إخفاقات المصادقة. لمعرفة سبب إيقاف طلب بعينه، انظر لماذا حُجب هذا؟.

​
1. رموز أخطاء أمان llm في لمحة

كل حجب أمني يعيد HTTP 400 بجسم خطأ على هيئة OpenAI (error.code هو السلسلة المُصنّفة أدناه). على مسارات Claude الأصلية (/v1/messages) يسافر نفس الرمز في هيئة خطأ Claude، فيكون توجيه SDK حتمياً عبر البروتوكولات.
الرمزيوقفتكلفة الحصة
guardrail_blockedمطالبة أو استجابة اصطدمت بقاعدة blockلا شيء
firewall_blockedاستدعاء أداة / إعلان مرفوضلا رموز نموذج
firewall_approval_pendingاستدعاء أداة مُعلَّق لمراجِع بشريلا رموز نموذج
تفرّع على error.code، لا على سلسلة الرسالة أبداً. تسمّي الرسائل حاجز الحماية أو القاعدة أو الأداة المحدّدة وستتغيّر؛ أما الرموز فعقد مستقر.

​
2. guardrail_blocked — مطالبة أو استجابة مفحوصة

يُعاد عندما تُطلق قاعدة حاجز حماية بإجراء block — كلمة مفتاحية في قائمة الرفض، أو اصطدام regex، أو كيان PII أو سرّ اخترت حجبه بدلاً من إخفائه، أو حكم llm_judge، أو فحص ترسيخ فاشل. HTTP 400. تسمّي الرسالة حاجز الحماية والقاعدة التي أُطلقت.
الطلب المحجوب لا يكلّف أي حصة. حجب مرحلة الإدخال يُطلق قبل القياس، فلا يُفوتر شيء أبداً. حجب مرحلة الإخراج يعمل بعد أن يستجيب النموذج، فتُرجِع البوابة الحصة المستهلكة مسبقاً قبل إعادة الخطأ. في الحالتين لا تدفع شيئاً مقابل استدعاء محجوب.
الحكم خاصية من خصائص المحتوى، لا القناة. إعادة تشغيل نفس المطالبة — حتى مقابل نموذج مختلف — تنتج نفس الحجب. أصلح الإدخال (أو السياسة) بدلاً من إعادة المحاولة.
قواعد mask لا تعيد هذا الرمز. التطابق المُخفى (مثل jane@acme.com ← [EMAIL]) يُنقَّح في مكانه ويمضي الاستدعاء بشكل طبيعي — تحصل على 200، لكن بالمقطع الحساس مُزالاً. إجراء block وحده يُظهر guardrail_blocked. (flag لا يغيّر أي شيء في حركة المرور على الإطلاق.)
{
  "error": {
    "type": "openai_error",
    "code": "guardrail_blocked",
    "message": "request blocked by guardrail \"pii-shield\": rule ssn (block)"
  }
}
لأنواع القواعد والمراحل والإجراءات خلف هذا الرمز، انظر حواجز الحماية. لظرف الخطأ حقلاً بحقل، انظر حمولات Webhook والأخطاء.

​
3. firewall_blocked — استدعاء أداة مرفوض

يُعاد عندما يحلّ جدار الحماية حكم deny لاستدعاء أداة — أمر shell مدمّر، أو جلب على هيئة SSRF، أو وجهة egress في قائمة رفض، أو مهارة في وضع block. كيفية ظهور الرفض تعتمد على سطح الفرض:

inbound / response / egress

HTTP 400 بـ error.code = firewall_blocked. يحمل الجسم error.metadata مهيكلة (reason_code، عوامل المخاطرة factors، risk_score) حتى تستطيع تفسير الحجب، لا مجرد رؤيته.

سطح mcp

يُعاد كـخطأ أداة (firewall deny: <reason>)، لا فشل نقل — فيرى النموذج الرفض ويمكنه اختيار أداة أخرى، أو سؤال المستخدم، أو التوقف، بدلاً من انهيار التشغيل.
sanitize ليس حجباً. حكم sanitize ينقّح السلاسل الفرعية المطابقة من وسائط استدعاء الأداة ويمرّر الاستدعاء المنظَّف — ولا يعيد firewall_blocked أبداً. (الاستثناء الوحيد: على سطح inbound، حيث لا توجد بعد وسائط وقت الاستدعاء، يتصاعد sanitize إلى رفض.)
{
  "error": {
    "type": "openai_error",
    "code": "firewall_blocked",
    "message": "tool \"shell.exec\" blocked by firewall: denied tool",
    "metadata": {
      "reason_code": "FW-TOOL-001",
      "risk_score": 92,
      "factors": ["denied_tool"]
    }
  }
}
من حيث الحصة، حجب inbound يُطلق قبل استدعاء النموذج الأعلى، فلا يكلّف أي رموز نموذج. انظر مسرد الأحكام لكل حكم، واستدعاءات الأدوات الخطرة للتهديدات التي يدافع عنها هذا الرمز.

​
4. firewall_approval_pending — مُعلَّق لإنسان

يُعاد في اللحظة التي يصطدم فيها استدعاء أداة بحكم pending_approval. بوابة الإنسان في الحلقة لا يمكن أن تكون انتظاراً مضمّناً حاجباً، فتعيد البوابة استجابة مُعلَّقة فوراً بدلاً من الاستطلاع الطويل. HTTP 400. يحمل الخطأ معرّف الموافقة حتى يعرف وكيلك أي تعليق يحلّه. هذا هو الرمز الوحيد الذي تستجيب له بـالحل وإعادة التقديم — لا بمعاملته كفشل نهائي:
1

اقرأ معرّف الموافقة من الخطأ المُعلَّق

المعرّف قابل للاسترداد من جسم الخطأ. لا تعِد محاولة الاستدعاء بعد — إعادة المحاولة الساذجة تعيد التعليق فحسب.
2

انتظر قراراً

يحلّها مراجِع من وحدة التحكم (Developer+)، أو يحصل نظام موافقاتك على استدعاء webhook مُوقَّع بـ HMAC. يستطلع وكيلك GET /api/v1/firewall/approvals/:id للحالة.
3

أعد التقديم برمز الموافقة

بمجرد الموافقة، أعد إصدار الاستدعاء الأصلي حاملاً ترويسة X-OrcaRouter-Firewall-Approval أحادية الاستخدام. تتعرّف البوابة على المعرّف وتمرّر ذلك الاستدعاء الواحد.
تعمل مسارات الموافقة (/api/v1/firewall/approvals/*) على مفتاح ضمن نطاق بوابة جدار الحماية، وليس جلسة وحدة التحكم. انظر الموافقة البشرية (HITL) للحلقة الكاملة وحمولات Webhook لتوقيع الاستدعاء الراجع.

​
5. لماذا تتخطّى الثلاثة جميعاً إعادة المحاولة

منطق إعادة محاولة SDK المعتاد يفترض أن 400 قد ينجح في محاولة ثانية. هذه الرموز تكسر هذا الافتراض — الحجب حتمي، فإعادة المحاولة العمياء تهدر رحلة ذهاب وإياب و(للاستدعاءات المُعلَّقة) تعيد إدراج موافقة في الطابور صامتةً.
آلية إعادة المحاولة/التراجع الداخلية الخاصة بـ OrcaRouter لا تعيد أبداً محاولة استدعاء يعيد أحد هذه الرموز مقابل قناة أخرى. عاكِس ذلك في عميلك: على رمز أمني، توقّف وتصرّف بناءً على الحكم، لا تكرّر.
  • guardrail_blocked ← أصلح الإدخال أو خفّف السياسة؛ أظهر الرفض للمستخدم. لا تعِد المحاولة.
  • firewall_blocked ← الإجراء غير مسموح؛ اجعل الوكيل يختار أداة مختلفة أو يطلب المساعدة. لا تعِد المحاولة.
  • firewall_approval_pending ← حُلّ التعليق، ثم أعد التقديم مرة واحدة بترويسة الموافقة (§4). إعادة المحاولة بدون الترويسة تعيد التعليق.

​
6. ملخّص الحصة والفوترة

الحجب الأمني لا يفوترك أبداً مقابل وحدة العمل المحجوبة.
الرمزمتى يُطلقنتيجة الفوترة
guardrail_blocked (إدخال)قبل استدعاء النموذجلا يُقاس أبداً
guardrail_blocked (إخراج)بعد أن يستجيب النموذجتُرجَع الحصة المستهلكة مسبقاً
firewall_blocked (inbound)قبل استدعاء النموذجلا رموز نموذج
firewall_approval_pendingقبل الإرساللا رموز نموذج
قاعدة llm_judge أو grounding في حاجز الحماية تستدعي فعلاً نموذجاً للوصول إلى حكمها، وتلك رموز المحكِّم تُفوتر كسطر فرعي منفصل للمحكِّم — حتى عندما يكون الحكم حجباً. تلك تكلفة الفحص، لا تكلفة الطلب المحجوب نفسه.

​
7. مراجع ذات صلة

لماذا حُجب هذا؟

تتبّع حجباً واحداً إلى القاعدة والسطح والسبب الدقيق الذي أنتجه.

مسرد الأحكام

كل حكم لجدار الحماية — allow وaudit وdeny وsanitize وpending_approval وcap_cost — وما يصدره كل منها.

حمولات Webhook والأخطاء

ظرف الخطأ الكامل، وحقول error.metadata، وتوقيع الاستدعاء الراجع للموافقة.

أوضاع الفرض

الظل والمراقبة والفرض — متى يغيّر الحكم فعلاً حركة المرور.
للتحكّمات التي تنتج هذه الرموز، انظر حواجز الحماية وجدار الحماية؛ وللمفردات، انظر مسرد المفاهيم.