الأخطاء

كل خطأ من واجهة K-Agent البرمجية له الشكل نفسه، ورمز code ثابت تستطيع البناء عليه، ورسالة مكتوبة للناس بالعربية أو الإنجليزية.

غلاف الخطأ

{
  "error": {
    "type": "conflict_error",
    "code": "session_busy",
    "message": "الجلسة مشغولة بالرد على رسالة أخرى. أعد المحاولة بعد لحظات.",
    "request_id": "req_01k6rz9f1j3m5p7r9t1w3y5a7c",
    "doc_url": "https://k-agent.kerneltics.com/docs/en/reference/errors/#session_busy"
  }
}

الحقل	الوصف
type	الفئة العامة، أدناه.
code	ثابت، بصيغة snake_case. ابنِ عليه. قد تُضاف رموز جديدة؛ فتعامل مع الرموز غير المعروفة حسب type وحالة HTTP.
message	للناس، بلغة Accept-Language ‏(ar أو en). قد تتغير في أي وقت — لا تحلّلها أبدًا.
param	يظهر حين يكون الخطأ في معامل واحد: اسم حقل، أو مؤشر JSON مثل /tools/max_tool_rounds.
request_id	القيمة نفسها التي في ترويسة الاستجابة Request-Id. اذكرها عند التواصل مع الدعم.
doc_url	رابط إلى هذه الصفحة، عند صف الرمز (النسخة الإنجليزية؛ والصفوف نفسها هنا بالعربية).

الأنواع والحالات

type	حالة HTTP	المعنى
invalid_request_error	400 (طلب مشوّه)، و422 (مفهوم لكنه غير صالح)، إضافة إلى 405 و413 و428	أصلح الطلب.
authentication_error	401	بيانات الاعتماد مفقودة أو غير صالحة أو منتهية أو مُلغاة.
permission_error	403	بيانات الاعتماد صالحة لكنها لا تملك هذا الإذن.
not_found_error	404	غير موجود — أو تابع لمشروع آخر أو لعميل آخر.
conflict_error	409، أو 412 عند قيمة If-Match قديمة	الحالة الراهنة لا تسمح بالطلب.
rate_limit_error	429	طلبات كثيرة جدًا؛ انتظر Retry-After.
quota_error	429	بُلغ حد في الخطة أو في التكلفة.
provider_error	502	فشل مزوّد الذكاء الاصطناعي.
api_error	500 و503	حدث خطأ من جهتنا.

إعادة المحاولة بأمان

• أعد المحاولة عند 429 بعد ثواني Retry-After، وعند 409 session_busy وsession_queue_full وidempotency_in_progress بعد مهلة قصيرة، وعند 500 و502 و503 بفواصل متزايدة. والرموز الموسومة بـ قابل لإعادة المحاولة أدناه هي التي تستحق ذلك.
• لا تُعد المحاولة حين تحمل الاستجابة x-should-retry: false (مثل quota_exceeded)، ولا عند أخطاء 4xx الأخرى — أصلح الطلب أولًا.
• أرسل دائمًا Idempotency-Key مع طلبات POST التي قد تعيدها، فلا تنشئ إعادة المحاولة أبدًا رسالة أو جلسة أو تذكرة ثانية. انظر عدم التكرار.

الأخطاء في البث

الأخطاء التي تقع قبل بدء البث استجابات JSON عادية. وبعد بدئه ينتهي التشغيل الفاشل بحدث run.failed يحمل run.error، ولا يُستخدم حدث error إلا لأعطال البث (token_expired وstream_timeout وinternal_error). انظر التشغيلات والبث.

رموز الأخطاء

طلب غير صالح (400 و405 و413 و422 و428)

الرمز	المعنى · ما العمل
allowed_origins_required HTTP 422	يحتاج المفتاح القابل للنشر إلى مصدر مسموح به واحد على الأقل، مثل https://www.example.com. ما العمل: أضف مصدرًا واحدًا على الأقل بالصيغة scheme://host[:port] إلى allowed_origins في المفتاح القابل للنشر.
credential_invalid HTTP 422	رفض مزوّد الذكاء الاصطناعي هذا المفتاح. تحقّق منه ثم أعد المحاولة. ما العمل: رفض المزوّد المفتاح أثناء التحقق المباشر. انسخ المفتاح مجددًا من لوحة المزوّد وتأكد من أنه يستطيع استدعاء النموذج المختار.
draft_not_allowed HTTP 422	لا يمكن تشغيل المسودة إلا في جلسات التجربة. ما العمل: لا يعمل version: "draft" إلا في جلسات التجربة (channel: "playground") لمن لديه دور محرر أو مفتاح بنطاق agents:write. انشر الإصدار لتستخدم التغييرات في أي مكان آخر.
external_id_invalid HTTP 422	صيغة المعرّف الخارجي (external_id) غير صالحة. استخدم من 1 إلى 128 من الحروف اللاتينية أو الأرقام أو الرموز . _ : -، على أن يبدأ بحرف أو رقم. لا يجوز أن يبدأ معرّف الجلسة بـ sess_ ولا معرّف العميل بـ eu_. ما العمل: استخدم من 1 إلى 128 حرفًا من A–Z a–z 0–9 . _ : -، تبدأ بحرف أو رقم. ولا يبدأ معرّف الجلسة بـ sess_، ولا معرّف العميل بـ eu_.
idempotency_key_reused HTTP 422	سبق استخدام مفتاح Idempotency-Key هذا مع طلب مختلف. استخدم مفتاحًا جديدًا لكل طلب جديد. ما العمل: استخدم Idempotency-Key جديدًا لكل طلب مختلف، ولا تُعِد استخدام المفتاح إلا لإعادة الطلب نفسه حرفيًا.
identity_as_parameter HTTP 422	يجب ألا تطلب الأدوات التي تشترط عميلًا موثّقًا بيانات الهوية من النموذج، مثل رقم الجوال أو البريد الإلكتروني. استخدم العناصر النائبة end_user بدلًا من ذلك. ما العمل: احذف معاملات الجوال أو البريد أو معرّف المستخدم من الأدوات التي تشترط عميلًا موثّقًا، واستخدم العناصر النائبة {{end_user.external_id}} أو {{end_user.traits.*}} بدلًا منها.
if_match_required HTTP 428	يتطلب هذا التعديل ترويسة If-Match تحمل قيمة etag الحالية. ما العمل: أرسل If-Match: <etag> بقيمة etag الحالية للمسودة عند تعديل إعدادات الوكيل عبر PATCH.
input_too_large HTTP 413	النص المُدخل أطول من المسموح. ما العمل: اختصر النص: الحد 4,000 حرف مع بيانات اعتماد المتصفح، و32,000 حرف مع المفتاح السري.
invalid_api_version HTTP 400	تشير الترويسة K-Agent-Version إلى إصدار API غير معروف. ما العمل: أرسل K-Agent-Version: 2026-10-06، أو احذف الترويسة.
invalid_cursor HTTP 400	مؤشر التصفح غير صالح لهذه القائمة. ما العمل: استخدم first_id أو last_id من صفحة سابقة للقائمة نفسها، ولا ترسل after وbefore معًا.
invalid_idempotency_key HTTP 400	يجب أن يتراوح طول الترويسة Idempotency-Key بين 1 و255 حرفًا. ما العمل: اجعل طول Idempotency-Key بين 1 و255 حرفًا؛ معرّف UUID خيار مناسب.
invalid_json HTTP 400	محتوى الطلب ليس بصيغة JSON صحيحة. ما العمل: أرسل محتوى JSON صحيحًا. تحقّق من علامات التنصيص والفواصل الزائدة.
invalid_parameter HTTP 400	قيمة المعامل "{param}" غير صالحة. ما العمل: صحّح القيمة المذكورة في param؛ يسرد مرجع الواجهة البرمجية القيم المسموح بها.
method_not_allowed HTTP 405	لا تدعم نقطة الوصول هذه طريقة HTTP المستخدمة. ما العمل: استخدم طريقة HTTP الموضحة لهذا المسار في مرجع الواجهة البرمجية.
model_not_allowed_on_plan HTTP 422	هذا النموذج غير متاح في خطتك الحالية. ما العمل: اختر نموذجًا تسمح به خطتك (يعرض GET /v1/models الحقل allowed_on_plan) أو رقِّ خطتك.
override_not_allowed HTTP 422	لا يسمح هذا الوكيل بتغيير هذا الإعداد في كل طلب على حدة. ما العمل: أضف الحقل إلى overrides.allowed في الوكيل (والنموذج إلى overrides.models)، ثم انشر وأعد المحاولة. لا يمكن تجاوز never_handle وescalation_reply وصلاحيات الأدوات أبدًا.
placeholder_unresolved HTTP 422	لم تتوفر قيمة لأحد العناصر النائبة في رابط الأداة أو ترويساتها أو محتواها، لذا لم يُنفَّذ الاستدعاء. ما العمل: عنصر نائب {{…}} في رابط الأداة أو ترويساتها أو جسمها بلا قيمة، فلم يُرسل شيء. اجعل المعامل إلزاميًا، أو مرّر المتغير، أو تحقّق من خصائص العميل.
project_mismatch HTTP 400	تشير الترويسة X-Project-Id إلى مشروع غير المشروع الذي يتبع له هذا المفتاح أو الرمز. ما العمل: مفاتيح API والرموز تنتمي إلى مشروع بالفعل. احذف الترويسة X-Project-Id، أو استخدم مفتاحًا من ذلك المشروع.
project_required HTTP 400	حدّد المشروع بإرسال معرّفه في الترويسة X-Project-Id. ما العمل: يجب أن ترسل طلبات لوحة التحكم المعتمدة على الكوكيز الترويسة X-Project-Id. أما مع مفتاح API فالمشروع يُستنتج من المفتاح.
reference_not_found HTTP 422	تشير الإعدادات إلى عنصر غير موجود في هذا المشروع. ما العمل: تشير الإعدادات إلى معرّف (tool_… أو ks_… أو pcred_…) غير موجود في هذا المشروع. أنشئ العنصر أولًا أو صحّح المرجع.
request_too_large HTTP 413	حجم محتوى الطلب أكبر من المسموح. ما العمل: أبقِ حجم محتوى الطلب أقل من 1 ميغابايت (5 ميغابايت لمصادر المعرفة).
secret_host_not_allowed HTTP 422	لا يمكن إرسال السر إلا إلى المضيفات المدرجة في allowed_hosts الخاصة به. ما العمل: أضف مضيف الأداة إلى allowed_hosts في السر، أو استخدم سرًا مستقلًا لذلك المضيف.
secret_variable_not_persistable HTTP 422	لا تُرسَل المتغيرات السرية إلا مع رسالة واحدة أو طلب سؤال واحد، ولا تُخزَّن في الجلسة أبدًا. ما العمل: أرسل المتغيرات السرية مع كل طلب (ask أو messages)، وليس مع POST /v1/sessions أو PATCH.
system_message_not_allowed HTTP 400	لا تُقبل رسائل system وdeveloper، إذ تسري تعليمات الوكيل نفسه. ما العمل: احذف رسائل system وdeveloper وضع التعليمات في إعدادات الوكيل. إذا سمح الوكيل بتجاوز instructions_append فستُستخدم تعليماتٍ لهذا الطلب.
tool_name_conflict HTTP 422	تستخدم أداةٌ أخرى لدى هذا الوكيل الاسمَ نفسه. ما العمل: غيّر اسم الأداة: يجب أن يكون الاسم فريدًا بين الأدوات المدمجة وأدوات HTTP وأدوات جهة العميل لدى الوكيل.
tool_not_declared HTTP 400	يتضمن الطلب أداة لم يعرّفها الوكيل ضمن أدوات جهة العميل. ما العمل: لا ترسل في tools إلا الأدوات التي يعرّفها الوكيل ضمن أدوات جهة العميل، وبالأسماء نفسها.
tool_outputs_incomplete HTTP 422	أرسل نتيجة لكل استدعاء أداة معلّق. ما العمل: أرسل نتيجة واحدة لكل call_id في required_action.tool_calls.
tools_not_allowed_with_session HTTP 400	لا يمكن إرسال أدوات جهة العميل عندما يكون الطلب مرتبطًا بجلسة. ما العمل: احذف tools من طلبات الواجهة المتوافقة مع OpenAI المرتبطة بجلسة، أو استدعِ بدون جلسة.
unknown_event_type HTTP 422	تحتوي قائمة الأحداث على نوع غير موجود في دليل الأحداث. استخدم أنواع الأحداث الموجودة في الدليل أو ["*"]. ما العمل: لا تشترك إلا في أنواع الأحداث الواردة في قائمة دليل الويب هوك، أو في ["*"] لكلها.
unknown_field HTTP 400	الحقل "{param}" غير معروف. ما العمل: احذف الحقل المذكور في param. تُرفض الحقول غير المعروفة حتى لا يمر خطأ إملائي دون أن تلاحظه.
unknown_model HTTP 422	هذا النموذج غير معروف. ما العمل: استخدم معرّف نموذج من GET /v1/models.
unsupported_content_type HTTP 422	المحتوى النصي فقط هو المدعوم. ما العمل: أرسل نصًا فقط: input كسلسلة نصية أو بالصيغة [{"type":"text","text":"…"}].
unsupported_parameter HTTP 400	يستخدم الطلب معاملًا غير مدعوم. ما العمل: احذف n الأكبر من 1 وlogprobs وresponse_format: json_schema من طلبات الواجهة المتوافقة مع OpenAI.
url_not_allowed HTTP 422	هذا الرابط غير مسموح به. استخدم عنوانًا عامًا يبدأ بـ https://. ما العمل: استخدم عنوانًا عامًا يبدأ بـ https:// على المنفذ 443 أو 8443. العناوين الخاصة وعناوين الحلقة المحلية وبيانات السحابة الوصفية محظورة.
validation_failed HTTP 422	يحتوي الطلب على قيمة غير صالحة. ما العمل: صحّح القيمة في مؤشر JSON المذكور في param؛ وتوضح الرسالة سبب الخطأ.
variable_missing HTTP 422	لم تُرسَل قيمة أحد المتغيرات الإلزامية. ما العمل: أرسل كل متغير يحدده الوكيل كمتغير إلزامي (required).
variable_unknown HTTP 422	يحدد الطلب متغيرًا لم يُعرَّف في إعدادات هذا الوكيل. ما العمل: لا ترسل إلا المتغيرات التي يعرّفها الوكيل، وتحقّق من كتابة أسمائها.
webhook_endpoint_limit_reached HTTP 422	بلغ هذا المشروع الحد الأقصى لعدد نقاط استقبال الويب هوك. ما العمل: للمشروع 10 نقاط استقبال ويب هوك كحد أقصى. احذف إحداها، أو اشترك بنقطة موجودة في أحداث إضافية.

التحقق من الهوية (401)

الرمز	المعنى · ما العمل
authentication_required HTTP 401	يلزم التحقق من الهوية. أرسل مفتاح API في الترويسة Authorization بالصيغة "Bearer <key>". ما العمل: أرسل الترويسة Authorization: Bearer <key> مع مفتاح سري أو مفتاح قابل للنشر أو رمز عميل.
invalid_api_key HTTP 401	مفتاح API غير صالح أو منتهي الصلاحية أو مُلغى. ما العمل: المفتاح مكتوب خطأً أو منتهي الصلاحية أو مُستبدل أو مُلغى. أنشئ مفتاحًا جديدًا أو استبدله من لوحة التحكم.
invalid_client_token HTTP 401	رمز العميل غير صالح. ما العمل: أصدر رمز عميل جديدًا من خادمك عبر POST /v1/client_tokens.
invalid_credentials HTTP 401	البريد الإلكتروني أو كلمة المرور غير صحيحة. ما العمل: تحقّق من البريد وكلمة المرور. المحاولات الفاشلة المتكررة تخضع لحد المعدّل.
token_expired HTTP 401	انتهت صلاحية رمز العميل. اطلب رمزًا جديدًا. ما العمل: احصل على رمز عميل جديد (في الودجت: POST /v1/widget/token/refresh، ومن خادمك: POST /v1/client_tokens) وأعد فتح البث مع Last-Event-ID. يصل هذا الرمز إلى البث المفتوح كحدث error.

الصلاحيات (403)

الرمز	المعنى · ما العمل
csrf_check_failed HTTP 403	حُظر هذا الطلب لأنه صادر من موقع آخر. ما العمل: يجب أن تكون طلبات لوحة التحكم المعتمدة على الكوكيز من المصدر نفسه وبصيغة JSON. استخدم مفتاح API في تكاملات الخادم بدل الكوكيز.
insufficient_scope HTTP 403	لا يملك مفتاح API هذا النطاقات (scopes) التي يتطلبها الطلب. ما العمل: استخدم مفتاحًا يملك النطاق الذي يتطلبه هذا المسار (مثل runs:write أو sessions:read)، أو مفتاحًا بصلاحيات permissions: "all".
origin_not_allowed HTTP 403	مصدر هذا الموقع غير مسموح به لهذا المفتاح. أضفه إلى المصادر المسموح بها في إعدادات المفتاح. ما العمل: أضف هذا المصدر بالضبط (scheme://host[:port]) إلى allowed_origins في المفتاح القابل للنشر.
origin_required HTTP 403	يجب أن تصدر الطلبات التي تستخدم مفتاحًا قابلًا للنشر من متصفح يرسل الترويسة Origin. ما العمل: لا تعمل المفاتيح القابلة للنشر إلا من المتصفحات، لأنها ترسل الترويسة Origin. من الخادم استخدم مفتاحًا سريًا.
permission_denied HTTP 403	ليست لديك صلاحية لتنفيذ هذا الإجراء. الصلاحية المطلوبة: {permission}. ما العمل: لا يشمل دورك الصلاحية المذكورة في الرسالة. اطلب من أحد المسؤولين دورًا يتضمنها.
principal_not_allowed HTTP 403	لا يمكن استخدام هذا النوع من بيانات الاعتماد مع نقطة الوصول هذه. ما العمل: يتطلب هذا المسار مفتاحًا سريًا أو مستخدمًا في لوحة التحكم. المفاتيح القابلة للنشر ورموز العميل لا تستدعي إلا مسارات المتصفح المذكورة في صفحة «العملاء والهوية».
signup_closed HTTP 403	التسجيل مغلق على هذا الخادم. اطلب دعوة من أحد المسؤولين. ما العمل: اطلب دعوة من أحد المسؤولين.

غير موجود (404)

الرمز	المعنى · ما العمل
project_not_found HTTP 404	لم يُعثر على المشروع، أو أنك لست عضوًا فيه. تحقّق من الترويسة X-Project-Id. ما العمل: تحقّق من الترويسة X-Project-Id: المشروع غير موجود، أو لست عضوًا في منظمته.
resource_not_found HTTP 404	تعذّر العثور على {resource}. ما العمل: تحقّق من المعرّف أو الـ slug. العناصر التابعة لمشروع آخر أو لعميل آخر تعيد 404 أيضًا.
route_not_found HTTP 404	لا توجد نقطة وصول بهذا المسار. تحقّق من الرابط في مرجع API. ما العمل: طابق المسار مع مرجع الواجهة البرمجية، بما في ذلك البادئة /v1.
session_not_found HTTP 404	لم يُعثر على الجلسة. أنشئ الجلسات عبر POST /v1/sessions، ثم استخدم معرّفها أو معرّفك الخارجي (external_id). ما العمل: أنشئ الجلسات عبر POST /v1/sessions (جلب أو إنشاء)، ثم خاطبها بمعرّف sess_… أو بمعرّفك external_id.

تعارض (409 و412)

الرمز	المعنى · ما العمل
agent_archived HTTP 409	هذا الوكيل مؤرشف ولم يعد يرد على الرسائل الجديدة. ما العمل: أُرشف هذا الوكيل (DELETE /v1/agents/{agent}). استخدم وكيلًا آخر، أو أنشئ وكيلًا جديدًا من ملف تصديره.
agent_not_ready HTTP 409	الوكيل غير جاهز للرد بعد. راجع العوائق المذكورة في حالة جاهزيته. ما العمل: راجع readiness.blockers في كائن الوكيل (GET /v1/agents/{agent}): اربط مفتاح المزوّد، أو اختر نموذجًا تسمح به خطتك، أو أوقف ai_paused. لن تفيد إعادة المحاولة قبل إزالة العائق.
already_member HTTP 409	هذا الشخص عضو في المؤسسة بالفعل. ما العمل: الشخص عضو في المنظمة بالفعل؛ غيّر دوره بدلًا من ذلك.
client_message_id_conflict HTTP 409	سبق استخدام المعرّف client_message_id هذا لرسالة مختلفة. ما العمل: أعدت استخدام client_message_id مع محتوى مختلف. أنشئ معرّفًا جديدًا لكل رسالة جديدة، ولا تُعِد استخدامه إلا لإعادة إرسال الرسالة نفسها.
email_taken HTTP 409	يوجد حساب مسجّل بهذا البريد الإلكتروني. سجّل الدخول بدلًا من ذلك. ما العمل: سجّل الدخول بدلًا من ذلك، أو أنشئ حسابًا ببريد آخر.
etag_mismatch HTTP 412	تغيّر هذا العنصر منذ أن حمّلته. أعد تحميله ثم طبّق تغييراتك من جديد. ما العمل: تغيّرت المسودة بعد قراءتك لها. اجلب الوكيل من جديد، وأعد تطبيق تعديلك، وأرسل قيمة etag الجديدة في If-Match.
handoff_already_assigned HTTP 409	استلم عضو آخر في الفريق هذا التحويل بالفعل. ما العمل: استلمه زميل قبلك. حدّث قائمة الانتظار، ويمكن للمسؤولين إعادة الإسناد مع force: true.
handoff_already_open HTTP 409	يوجد تحويل مفتوح لهذه الجلسة بالفعل. ما العمل: لهذه الجلسة تحويل مفتوح بالفعل. تابعه في مكتب التحويل، أو أنهِه قبل طلب تحويل آخر.
handoff_not_open HTTP 409	لم يعد هذا التحويل مفتوحًا. ما العمل: أُغلق التحويل أو انتهت مدته بالفعل. حدّثه قبل أي إجراء.
idempotency_in_progress HTTP 409 قابل لإعادة المحاولة	ما زال طلب يحمل مفتاح Idempotency-Key نفسه قيد المعالجة. أعد المحاولة بعد اكتماله. ما العمل: ما زال الطلب الأول بهذا المفتاح قيد التنفيذ. أعد المحاولة بفواصل متزايدة، وستحصل على نتيجته المحفوظة عند اكتماله.
invitation_expired HTTP 409	انتهت صلاحية هذه الدعوة أو أُلغيت. اطلب دعوة جديدة. ما العمل: اطلب رابط دعوة جديدًا من أحد المسؤولين. الرابط يُستخدم مرة واحدة وتنتهي صلاحيته بعد 7 أيام.
last_owner HTTP 409	يجب أن يبقى للمؤسسة مالك واحد على الأقل. ما العمل: اجعل عضوًا آخر مالكًا قبل إزالة هذا العضو أو تغيير دوره.
model_not_configured HTTP 409	لا يوجد مفتاح API مُعدّ لمزوّد هذا النموذج. أضف مفتاح المزوّد من الإعدادات. ما العمل: اربط مفتاحًا لمزوّد النموذج (الإعدادات ← مزوّدو النماذج، أو POST /v1/provider_credentials)، أو اختر نموذجًا توفّره المنصة.
name_taken HTTP 409	هذا الاسم مستخدم بالفعل. اختر اسمًا مختلفًا. ما العمل: اختر اسمًا أو معرّفًا نصيًا (slug) مختلفًا.
no_open_handoff HTTP 409	لا يوجد تحويل مفتوح لهذه الجلسة. ما العمل: لا يوجد تحويل مفتوح لإعادته أو إنهائه. اجلب الجلسة وتحقّق من mode.
run_already_completed HTTP 409	انتهى هذا التشغيل بالفعل ولا يمكن إلغاؤه. ما العمل: انتهى التشغيل بالفعل. لا يلزمك فعل شيء.
run_not_requires_action HTTP 409	هذا التشغيل لا ينتظر نتائج أدوات. ما العمل: لا ترسل نتائج الأدوات إلا وحالة التشغيل requires_action. اجلب التشغيل لترى حالته.
session_agent_mismatch HTTP 409	المعرّف الخارجي (external_id) هذا مرتبط بجلسة لوكيل آخر. ما العمل: هذا external_id مرتبط بجلسة لوكيل آخر. استخدم معرّفًا مختلفًا لكل وكيل، مثلًا بإضافة slug الوكيل في أوله.
session_busy HTTP 409 قابل لإعادة المحاولة	الجلسة مشغولة بالرد على رسالة أخرى. أعد المحاولة بعد لحظات. ما العمل: الجلسة مشغولة بالرد على رسالة أخرى وتستخدم concurrency: "reject". انتظر عدد ثواني Retry-After، أو حوّل الجلسة إلى queue.
session_closed HTTP 409	هذه الجلسة مغلقة. ما العمل: أرسلت if_closed: "error". اتركه على القيمة الافتراضية reopen لإعادة فتح الجلسة، أو ابدأ جلسة جديدة.
session_end_user_mismatch HTTP 409	هذه الجلسة تخص عميلًا آخر. ما العمل: الجلسة تخص عميلًا آخر، وعميل الجلسة لا يتغير أبدًا. استخدم معرّف جلسة مختلفًا.
session_exists HTTP 409	توجد جلسة بهذا المعرّف الخارجي (external_id) بالفعل. ما العمل: أرسلت if_exists: "error" والجلسة موجودة. احذف الخيار لاستئنافها، أو استخدم external_id جديدًا.
session_queue_full HTTP 409 قابل لإعادة المحاولة	توجد رسائل كثيرة بانتظار الرد في هذه الجلسة. انتظر رد الوكيل ثم أعد المحاولة. ما العمل: توجد عشر رسائل بانتظار الرد في هذه الجلسة. انتظر الردود قبل إرسال المزيد.
slug_taken HTTP 409	يستخدم وكيل آخر في هذا المشروع هذا المعرّف النصي (slug) بالفعل. ما العمل: يستخدم وكيل آخر في هذا المشروع هذا المعرّف النصي. اختر slug مختلفًا.

حدود المعدّل والحصة (429)

الرمز	المعنى · ما العمل
anonymous_limit_reached HTTP 429 قابل لإعادة المحاولة	عدد الرسائل كبير حاليًا. يُرجى المحاولة لاحقًا. ما العمل: بلغ زائر مجهول في الودجت أحد الحدود (لكل عنوان IP أو لكل جلسة أو الحد اليومي). اطلب منه المحاولة لاحقًا، أو عرّف المستخدمين المسجّلين برموز العميل.
cost_cap_exceeded HTTP 429	بُلغ الحد اليومي للاستخدام. يُرجى المحاولة غدًا. ما العمل: بلغت المنظمة الحد اليومي لتكلفة النماذج. حتى اليوم التالي تُحوَّل الجلسات لموظف ويعيد ask الرمز 429. تواصل معنا لرفع الحد.
playground_limit_reached HTTP 429	بُلغ الحد اليومي لمحادثات التجربة. اربط مفتاح المزوّد الخاص بك لمواصلة التجربة. ما العمل: لتشغيلات لوحة التجربة على نماذج المنصة حد يومي لكل مشروع. اربط مفتاح مزوّدك لمواصلة التجربة، أو جرّب غدًا.
quota_exceeded HTTP 429	استُنفدت حصة المحادثات الذكية في خطتك لهذا الشهر. ما العمل: استُنفدت المحادثات الذكية لهذا الشهر في الخطة (الخطة المجانية، أو خطة مدفوعة بسقف صارم). رقِّ خطتك أو انتظر الشهر التالي؛ تحمل الاستجابة x-should-retry: false.
rate_limited HTTP 429 قابل لإعادة المحاولة	عدد الطلبات كبير جدًا. انتظر قليلًا ثم أعد المحاولة. ما العمل: انتظر عدد الثواني المذكور في Retry-After ثم أعد المحاولة، ووزّع طلباتك على فترات.

مزوّد الذكاء الاصطناعي (502)

الرمز	المعنى · ما العمل
provider_auth_failed HTTP 502	رفض مزوّد الذكاء الاصطناعي بيانات الاعتماد. ما العمل: رفض مزوّد النموذج بيانات الاعتماد. تحقّق من مفتاح المزوّد أو استبدله.
provider_bad_request HTTP 502	رفض مزوّد الذكاء الاصطناعي الطلب. ما العمل: رفض المزوّد الطلب. راجع إعدادات النموذج، وإن تكرر الخطأ فتواصل مع الدعم وأرفق request_id.
provider_error HTTP 502 قابل لإعادة المحاولة	أعاد مزوّد الذكاء الاصطناعي خطأً. ما العمل: أعد المحاولة لاحقًا. اضبط model.fallback_models لتكمل التشغيلات على نموذج آخر.
provider_overloaded HTTP 502 قابل لإعادة المحاولة	مزوّد الذكاء الاصطناعي مثقل بالطلبات حاليًا. أعد المحاولة بعد قليل. ما العمل: أعد المحاولة بفواصل متزايدة؛ وتُبقي model.fallback_models المحادثات مستمرة في الأثناء.
provider_rate_limited HTTP 502 قابل لإعادة المحاولة	يقيّد مزوّد الذكاء الاصطناعي عدد الطلبات حاليًا. أعد المحاولة بعد قليل. ما العمل: يقيّد المزوّد طلبات المفتاح. أعد المحاولة بفواصل متزايدة أو ارفع حدودك لدى المزوّد.
provider_refusal HTTP 502	امتنع نموذج الذكاء الاصطناعي عن الإجابة. ما العمل: امتنع النموذج عن الإجابة. يجرّب K-Agent النماذج البديلة fallback_models، ثم يرسل رسالة الطوارئ ويحوّل الجلسة لموظف.
provider_timeout HTTP 502 قابل لإعادة المحاولة	استغرق مزوّد الذكاء الاصطناعي وقتًا طويلًا في الرد. ما العمل: أعد المحاولة. وإن تكرر فاختر نموذجًا أسرع أو قيمة أصغر لـ max_reply_tokens.
provider_unavailable HTTP 502 قابل لإعادة المحاولة	مزوّد الذكاء الاصطناعي غير متاح حاليًا. ما العمل: أعد المحاولة لاحقًا، واضبط model.fallback_models.

الخادم (500 و503)

الرمز	المعنى · ما العمل
internal_error HTTP 500 قابل لإعادة المحاولة	حدث خطأ من جهتنا. أعد المحاولة، وإن تكرر الخطأ فتواصل مع الدعم وأرفق معرّف الطلب. ما العمل: أعد المحاولة بفواصل متزايدة. إن تكرر الخطأ فتواصل مع الدعم وأرفق request_id.
service_unavailable HTTP 503 قابل لإعادة المحاولة	الخدمة غير متاحة مؤقتًا. أعد المحاولة بعد قليل. ما العمل: الخادم يُعاد تشغيله أو مثقل بالطلبات. أعد المحاولة بفواصل متزايدة.

رموز خارج استجابات HTTP

هذه الرموز لا تعود خطأَ HTTP أبدًا. تظهر في error الخاص بالتشغيل (أخطاء التشغيل)، أو حدثَ error في البث، أو في نتيجة أداة لا يراها إلا النموذج — وتجدها في خطوات التشغيل وتبويب Debug في لوحة التحكم.

الرمز	المعنى · ما العمل
handed_off نتيجة أداة	حُوّلت المحادثة إلى أحد الموظفين. ما العمل: يُعاد إلى النموذج بدل بقية استدعاءات الأدوات في الجولة التي أنهى فيها تحويلٌ لسبب قانوني (liability) الدورَ. لا يلزمك فعل شيء.
no_model_credential خطأ تشغيل	لم يُربط أي مفتاح API بمزوّد الذكاء الاصطناعي الخاص بالوكيل. ما العمل: لا يوجد مفتاح API لمزوّد الذكاء الاصطناعي الخاص بالوكيل، فانتهى التشغيل برسالة الطوارئ. اربط مفتاح مزوّد (الإعدادات ← مزوّدو النماذج، أو POST /v1/provider_credentials). أما طلبات الواجهة البرمجية فتتلقى 409 agent_not_ready مع هذا العائق بدلًا من ذلك.
run_interrupted خطأ تشغيل قابل لإعادة المحاولة	انقطع التشغيل قبل أن يكتمل. ما العمل: توقف التشغيل قبل اكتماله (مثلًا أثناء إعادة تشغيل الخادم) وانتهى عبر مسار «عدم الصمت». راجع الجلسة وأعد إرسال الرسالة إن لزم.
stream_timeout حدث بث قابل لإعادة المحاولة	أُغلق البث لطول مدة فتحه. أعد الاتصال مع Last-Event-ID للمتابعة. ما العمل: أعد الاتصال مع Last-Event-ID (أو ?after=) لتكمل من آخر حدث استلمته.
ticket_already_open نتيجة أداة	لدى هذا العميل تذكرة مفتوحة بالفعل. ما العمل: يُعاد إلى النموذج حين تكون لدى العميل تذكرة مفتوحة، فيخبره برقم التذكرة القائمة. لا يلزمك فعل شيء.
too_many_calls نتيجة أداة	عدد استدعاءات الأدوات في الخطوة الواحدة أكبر من المسموح. ما العمل: تُنفَّذ 5 استدعاءات أدوات كحد أقصى في الجولة الواحدة، ويتلقى النموذج هذا الرمز للاستدعاءات الزائدة. لا يلزمك فعل شيء.
tool_outputs_expired خطأ تشغيل	انتهت مهلة انتظار نتائج الأدوات، فتوقّف التشغيل. ما العمل: يجب أن تصل نتائج الأدوات خلال 10 دقائق من requires_action. فشل التشغيل؛ أرسل رسالة جديدة للمتابعة.
unreadable نتيجة أداة	وصلت نتيجة الاستعلام بصيغة تعذّرت قراءتها. ما العمل: أعادت نقطة أداة HTTP لديك محتوى ليس JSON أو لا يطابق response.items_path وfields. أصلح النقطة أو الإسقاط، وتحقّق عبر POST /v1/tools/{tool}/test.
upstream_failed نتيجة أداة قابل لإعادة المحاولة	تعذّر إكمال الاستعلام في الوقت الحالي. ما العمل: فشلت نقطة أداة HTTP لديك (رمز غير 2xx، أو انتهاء المهلة، أو تجاوز 1 ميغابايت، أو عنوان محظور). راجع خطوات التشغيل واختبر الأداة.

التحذيرات

بعض الاستجابات الناجحة تحمل warnings: ملاحظات غير مانعة تستحق التسجيل.

التحذير	المعنى
external_id_looks_like_phone	يبدو external_id رقم هاتف. أبقِ البيانات الشخصية خارج المعرّفات، واحفظ بيانات التواصل في خصائص العميل.
external_id_looks_like_email	يبدو external_id عنوان بريد إلكتروني. والنصيحة نفسها.
create_params_ignored	الجلسة موجودة مسبقًا، فجرى تجاهل إعدادات الإنشاء الواردة في الطلب.
client_history_ignored	الواجهة المتوافقة مع OpenAI: استُخدم سجل الجلسة المحفوظ وجرى تجاهل الرسائل السابقة الواردة في الطلب.
identity_as_parameter	اسم معامل في أداة يبدو من بيانات الهوية الشخصية. فعّل requires_verified_user واستخدم العناصر النائبة end_user بدلًا منه.