الأخطاء

عندما يفشل طلب، تُرجع الواجهة غلاف خطأ بصيغة JSON بشكل مستقر. فرّع معالجة الأخطاء بناءً على الحقلين type وcode القابلين للقراءة آليًا — لا على message القابل للقراءة البشرية أبدًا (الذي قد يتغيّر).

غلاف الخطأ


{
  "error": {
    "type": "not_found_error",
    "code": "agent_not_found",
    "message": "No agent with that id exists.",
    "param": "agent_id"
  }
}

الحقل	النوع	المعنى
`type`	string	إحدى الـ فئات الثابتة السبع أدناه. يرتبط بحالة HTTP.
`code`	string	معرّف مستقر وقابل للقراءة آليًا لكل فشل (مثل `agent_not_found`).
`message`	string	وصف قابل للقراءة البشرية. للعرض/التسجيل فقط — لا تفرّع بناءً عليه.
`param`	string	(اختياري) حقل الطلب الذي سبّب الفشل، عند الانطباق.

الفئات

توجد سبع فئات أخطاء بالضبط. ترتبط كل منها بحالة HTTP ثابتة، لذا تتفق الفئة ورمز الحالة دائمًا.

`type`	حالة HTTP	متى يحدث	أمثلة `code`
`authentication_error`	`401`	الـ API key مفقودة أو مشوّهة أو ملغاة أو غير معروفة.	`invalid_api_key`
`permission_error`	`403`	تفتقر الـ key إلى الـ scope المطلوب، أو يفتقر الدور المُنشئ إلى إذن RBAC المرتبط.	`invalid_scope`, `permission_denied`
`tier_error`	`403`	لا تسمح خطتك بالعملية، أو يخرق إعدادٌ حدًّا من حدود الخطة.	`tier_limit`
`invalid_request_error`	`400`	كان الطلب مشوّهًا أو خالف قيدًا.	`invalid_cursor`, `invalid_upload`, `folder_name_exists`, `folder_not_empty`, `tag_name_exists`
`not_found_error`	`404`	لا يوجد مورد بذلك المعرّف في organization الخاصة بك.	`agent_not_found`, `document_not_found`
`rate_limit_error`	`429`	تجاوزت حصة طلبات أو استعلامات خطتك.	`rate_limit_exceeded`
`api_error`	`500`	حدث خطأ upstream غير متوقع — أعد محاولة الطلب.	`upstream_error`

الفئات إضافية ولا يُعاد توظيفها أبدًا — قد تُضاف فئة جديدة مستقبلًا، لكن فئة موجودة لن تغيّر معناها أبدًا، لذا من الآمن التفريع بناءً على type.

غير موجود، لا عبر organizations أبدًا

يُبلَّغ عن معرّف مورد ينتمي إلى organization مختلفة بالرمز 404 not_found_error، تمامًا كأنه غير موجود — لا تكشف الواجهة أبدًا عن وجود موارد خارج organization الخاصة بك عبر 403.

استثناء الرفع المكرّر

استجابة واحدة ليست عمدًا غلاف خطأ: عندما يطابق رفع مستند مستندًا موجودًا، يُرجع POST /knowledge/documents الرمز 409 مع جسم مُهيكَل DuplicateDetected (يحمل upload_session_id)، لا غلاف الخطأ. استأنف الرفع بـ POST /knowledge/documents/confirm-duplicate. راجع صفحة مستندات Knowledge للتدفق الكامل.


{
  "upload_session_id": "ups_abc123",
  "duplicate_of": ["doc_existing456"]
}