الأخطاء

هذه قائمة كاملة بالأخطاء التي قد تعيدها واجهة برمجة تطبيقات منصة Kaleidr. لكل خطأ حالة HTTP ورمز، وهو سلسلة قصيرة ثابتة يمكن للشيفرة اتخاذ قرار بناءً عليها. لا تكفي الحالة وحدها؛ فالرمز 403 قد يشير إلى أسباب مختلفة، وقد يعني 429 إما «خفّض معدل الطلبات» أو «نفدت حصتك».

ابدأ بأشكال الاستجابة، لأن الرمز لا يوجد دائمًا في الحقل نفسه.

أشكال الاستجابة

الشكل	مثال	مواضع الاستخدام
رمز مغلّف	`{"detail": "origin_not_allowed"}`	معظم أخطاء 401 و403 و404 و413 و500 و503، ورموز حدود الطلبات مع 422، وخطآن مع 429 (`map_load_quota_exceeded` و`ingest_rate_limited` من واجهة برمجة الرفع). الرمز هو سلسلة `detail`.
كائن مسطّح	`{"error": "rate_limited", "detail": "API key rate limit exceeded. Slow down."}`	بقية أخطاء 429. يوجد الرمز في `error`؛ بينما يحتوي `detail` على جملة موجّهة للمستخدم. وتضيف أخطاء الحصة حقولًا أخرى.
قائمة تحقق	`{"detail": [{"loc": ["body", "product"], "msg": "…", "type": "…"}]}`	استجابة 422 لمتن طلب أو استعلام غير صالح. الحقل `detail` مصفوفة فيها إدخال لكل مشكلة.
خطأ مع 200	`{"error": "Route planning failed."}`	يخص `POST /chat/control/route` فقط. راجع أدناه.

دالة تقرأ الرمز من أيٍّ من هذه الأشكال:

async function kaleidrError(res) {
  const body = await res.json().catch(() => ({}));
  const code =
    typeof body.error === 'string' ? body.error :      // flat 429
    typeof body.detail === 'string' ? body.detail :    // wrapped code
    Array.isArray(body.detail) ? 'validation_error' :  // 422
    'unknown_error';
  return { status: res.status, code, body, retryAfter: Number(res.headers.get('retry-after')) || null };
}

ترويسَتان مهمتان: Retry-After في استجابات 429، وقيمته بالثواني، وX-Request-Id عند وجودها، وهي تحدد الطلب إذا تواصلت مع الدعم.

المصادقة: 401

لا تقبل واجهة البرمجة بيانات الاعتماد.

الرمز	متى يحدث	ما الذي ينبغي فعله
`Invalid or missing API key`	لم تُرسل بيانات اعتماد، أو كان المفتاح غير معروف أو ملغى أو منتهي الصلاحية. وينطبق أيضًا على: رمز جلسة منتهي الصلاحية؛ أو جلسة أُلغي مفتاحها أو دُوِّر من دون فترة سماح؛ أو جلسة أُزيل مصدرها أو منتجها من المفتاح؛ أو جلسة صَدرت قبل تخفيض الخطة؛ أو مؤسسة معلّقة أو ليس لها خطة.	تحقّق من المفتاح وحالته في kaleidr.com/api-keys. بالنسبة إلى الجلسة، استبدلها مجددًا. إذا ظل مفتاح صالح يفشل، أعد المحاولة بعد لحظات؛ فقد تُعيد المنصة الخطأ نفسه عند عطل قصير.
`publishable_requires_session`	أُرسل مفتاح قابل للنشر (`kld_pk_…`) إلى نقطة نهاية لوقت التشغيل.	في المتصفح، دع حزمة التطوير تستبدله، أو استدعِ `POST /sdk/sessions` أولًا. في الخادم الخلفي، استخدم مفتاح خادم.

التفويض: 403

تتعرف واجهة البرمجة على بيانات الاعتماد لكنها ترفض هذا الطلب.

الرمز	متى يحدث	ما الذي ينبغي فعله
`insufficient_scope`	أُنشئ المفتاح دون نطاق الصلاحية الذي يحتاج إليه هذا المنتج أو نقطة النهاية.	استخدم مفتاحًا يحمل النطاق. لا يمكن إضافة نطاقات إلى مفتاح موجود.
`tier_capability_not_allowed`	يحمل المفتاح النطاق أو المنتج، لكن الخطة الحالية لمؤسستك لا تتضمنه. يظهر أيضًا للخريطة المنشورة عندما لا تتضمن خطة مالكها الدردشة. لا يظهر بالنسبة إلى `vendor`: فالمفتاح الذي يحمل `vendor` ضمن خطة أقل من Enterprise لا يُرفض، ولكن إجاباته تُنشأ من دون بياناتك.	غيّر الخطة أو استخدم منتجًا تتضمنه.
`server_key_in_browser`	أُرسل مفتاح خادم (`kld_sk_…`) مع ترويسة `Origin`.	انقل الاستدعاء إلى خادمك الخلفي. إذا ظهر المفتاح في مصدر الصفحة، فدوّره.
`session_origin_mismatch`	استُخدم رمز جلسة من مصدر مختلف عن مصدر إنشائه، أو استُخدمت جلسة خريطة منشورة دون `Origin`.	استبدل الجلسة على الصفحة التي ستستخدمها.
`ip_not_allowed`	استُخدم مفتاح خادم أو مفتاح قديم مقيّد بقائمة عناوين IP من عنوان خارجها، أو تعذّر معرفة عنوان المتصل.	اتصل من عنوان مسموح أو غيّر `allowed_ips` للمفتاح.
`publishable_key_required`	استُدعيت `POST /sdk/sessions` بمفتاح خادم أو مفتاح قديم.	استخدم مفتاحًا قابلًا للنشر للاستبدال.
`origin_required`	لم تتضمن عملية استبدال الجلسة ترويسة `Origin`.	أجرِ الاستبدال من صفحة متصفح.
`origin_not_allowed`	مصدر الصفحة غير موجود ضمن مصادر المفتاح المسموح بها أو نطاقات الخريطة المنشورة المسموح بها.	أضف المصدر المطابق إلى المفتاح أو النطاق إلى الخريطة.
`product_not_allowed`	المفتاح مقيّد بمنتجات معينة والطلب موجّه إلى منتج آخر. عند استبدال الجلسة، لا يكون `product` المطلوب ضمن المنتجات المسموح بها للمفتاح القابل للنشر. وعند نقطة نهاية لوقت التشغيل، يستدعي مفتاح خادم أو مفتاح قديم نقطة نهاية لمنتج غير مسموح به، مثل مفتاح مقيّد بـ`tile` يستدعي `/chat/*`.	غيّر `allowed_products` أو استخدم مفتاحًا آخر.
`chat_disabled`	استبدال خريطة منشورة: لا يفعّل Kaleidr AI الخاص بالخريطة الميزة المطلوبة.	فعّل Control Tower أو Popup Window في لوحة Kaleidr AI الخاصة بالخريطة في Studio.
`feature_not_granted`	استُخدمت جلسة خريطة منشورة مفتوحة لدردشة النافذة المنبثقة على `/chat/control/stream`. لكل ميزة جلستها الخاصة.	استبدل جلسة باستخدام `"feature": "control_tower"`، التي تمنحها الخريطة ما دام Control Tower مفعّلًا.
`owner_has_no_organization`	استبدال خريطة منشورة: ليس لمالك الخريطة مؤسسة يمكن تحميل التكلفة عليها.	يجب على المالك إنشاء مؤسسة أو الانضمام إليها.

غير موجود: 404

الرمز	متى يحدث	ما الذي ينبغي فعله
`not_found`	استبدال خريطة منشورة: لا توجد خريطة منشورة أو رابط مشاركة بهذا `share_id`.	تحقق من المعرّف ومن نشر الخريطة.
`sessions_disabled`	استبدال الجلسات معطل على المنصة.	لا يمكنك تغيير ذلك بنفسك. اتصل بالدعم.
`Not Found`	المسار غير موجود.	راجع عنوان URL في نقاط النهاية، بما في ذلك البادئة `/inference-api/b2b/v1`.

التحقق: 422

متن الطلب أو سلسلة الاستعلام لا يطابق ما تقبله نقطة النهاية. الحقل detail مصفوفة؛ ويسمّي loc في كل إدخال الحقل، بينما يوضح msg الخطأ.

{
  "detail": [
    { "type": "missing", "loc": ["body", "product"], "msg": "Field required", "input": {} }
  ]
}

صحّح الطلب ولا تعِد إرساله دون تغيير. تُعيد نقطتا البث /chat/summary/stream و/chat/button/stream الحالة 500 بدلًا من 422 عندما يكون متن الطلب غير صالح، باستثناء حالة الحقل الطويل جدًا (أدناه).

حدود الطلبات: 422 مع رمز

يُعاد أيضًا 422 لطلب صحيح البنية يتجاوز حد الحجم، ولكن بالصيغة المغلّفة: يكون detail سلسلة تحوي الرمز وليس مصفوفة. ولا تُحتسب أي تكلفة.

{ "detail": "conversation_too_long" }

الرمز	نقطة النهاية	متى يحدث	ما الذي ينبغي فعله
`too_many_messages`	`/chat/control/stream`	تحتوي `messages` على أكثر من 400 إدخال.	أرسل أحدث أدوار المحادثة فقط.
`message_too_long`	`/chat/control/stream`	يتجاوز `content` لإحدى الرسائل 64,000 حرف.	اختصر الرسالة.
`conversation_too_long`	`/chat/control/stream`	يتجاوز مجموع `content` لجميع الرسائل 200,000 حرف.	احذف الأدوار الأقدم وأعد الإرسال.
`invalid_session_id`	`/chat/control/stream`	يتجاوز `session_id` طول 128 حرفًا أو يحوي محارف غير الحروف والأرقام و`_` و`.` و`:` و`-`.	استخدم معرّفًا بهذه الصيغة، مثل UUID.
`lang_too_long`	`/chat/control/stream`	يتجاوز `lang` طول 35 حرفًا.	أرسل وسم لغة BCP 47 مثل `pt-BR`.
`invalid_layout`	`/chat/control/stream`	يتجاوز `layout` طول 16 حرفًا.	أرسل `guide` ما دام viewer يعرض تخطيط الدليل، أو احذف الحقل.
`field_too_long`	`/chat/summary/stream`, `/chat/button/stream`	يتجاوز حقل نصي الحد المسموح لطوله، أو تتجاوز قائمة الحد المسموح لعدد العناصر.	اختصر الحقل. الحدود موضحة في نقاط النهاية.

حدود بث الدردشة موضحة في نقاط النهاية.

الطلب كبير جدًا: 413

الرمز	متى يحدث	ما الذي ينبغي فعله
`request_too_large`	يتجاوز متن الطلب 2 MiB، أو 5 MiB في نقطة نهاية `/design/*`. يأتي المتن بالصيغة `{"detail": "request_too_large"}`. ولا تُحتسب تكلفة.	أرسل بيانات أقل: قلّص المحادثة أو صفوف العينة في طلب التصميم. لا تعِد إرسال المتن نفسه.
`request_body_too_large`	يتجاوز طلب إلى مسارات إدارة المفاتيح أو بيانات الأعمال ضمن `/shared-api` حجم 1 MiB، أو يتجاوز طلب الرفع `POST /shared-api/datahub/ingests` حجم 32 MiB.	أرسل متنًا أصغر. لرفع الملفات راجع رفع بيانات أعمالك.

يمكن رفض طلب يصرّح بحجم يفوق بكثير حدود أي نقطة نهاية عند حافة الشبكة قبل وصوله إلى واجهة البرمجة. ولا يحتوي هذا الرد على متن Kaleidr بصيغة JSON، ولذلك لا يوجد رمز لقراءته؛ قلّل البيانات.

لا يُحاسَب الطلب المرفوض بسبب حجمه، كأي طلب يُرفض قبل معالجته، ولا يحجز بعد ذلك أرصدة ذكاء اصطناعي أو فتحة للطلبات المتزامنة.

حدود الحصة ومعدل الطلبات: 429

اقرأ متن الاستجابة قبل أن تقرر إعادة المحاولة.

الرمز	الحقل	`Retry-After`	متى يحدث	ما الإجراء المطلوب
`quota_exceeded`	`error`	ثوانٍ حتى `reset_at`	لا تكفي أرصدة الذكاء الاصطناعي لدى مؤسستك لتغطية الطلب، أو أن الطلب سيتجاوز الحد الشهري الخاص بالمفتاح. ويُعاد هذا الرمز أيضًا من طلب اقتراح تعيين الأعمدة في واجهة API الخاصة بالتحميل.	لا تُعِد المحاولة. انتظر حتى `reset_at`، أو أضف أرصدة، أو ارفع الحد الخاص بالمفتاح.
`rate_limited`	`error`	`5`	استُنفد الحد المسموح لطلبات المفتاح في الدقيقة. ويحدث كذلك عند كثرة عمليات تبادل الجلسات لمفتاح أو خريطة منشورة أو عنوان واحد.	انتظر عدد الثواني المحدد في `Retry-After`، ثم أعد المحاولة مع إضافة تأخير عشوائي بسيط.
`org_overloaded`	`error`	`5`	لدى مؤسستك عدد كبير جدًا من الطلبات قيد التنفيذ في الوقت نفسه.	انتظر حتى ينتهي طلب قيد التنفيذ، ثم أعد المحاولة. وأغلق تدفقات الاستجابة التي لم تعد تحتاج إليها.
`b2b_overloaded`	`error`	`5`	بلغت واجهة API سعتها القصوى لجميع المتصلين.	انتظر عدد الثواني المحدد في `Retry-After`، ثم أعد المحاولة مع زيادة مدة الانتظار تدريجيًا.
`limiter_unavailable`	`error`	`5`	تعذّر الحصول على استجابة من محدِّد معدل الطلبات.	أعد المحاولة بعد قليل. ليست المشكلة مرتبطة بمعدل طلباتك.
`visitor_limit_reached`	`error`	`5`	تجاوز أحد زوار محادثة خريطة منشورة الحد المسموح من الطلبات في الدقيقة أو اليوم.	أبلغ الزائر بأن يحاول مرة أخرى لاحقًا.
`map_load_quota_exceeded`	`detail`	لا يوجد	بالنسبة إلى `POST /sdk/sessions` مع `tile`: استُنفد رصيد تحميلات الخرائط لدى المؤسسة.	لا تُعِد المحاولة. انتظر إعادة ضبط الفترة أو أضف حزمة تحميلات خرائط.

يحمل متن quota_exceeded القيم الرقمية التالية:

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "product": "b2b",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 4999100,
  "remaining": 900,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

هذا هو المتن الذي يتلقاه مفتاح الخادم. أما الطلب المرسل برمز جلسة (صادر عن استبدال مفتاح قابل للنشر أو جلسة زائر لخريطة منشورة) فيتلقى متنًا أقصر لا يكشف خطة المؤسسة أو استخدامها:

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "meter": "b2b.tokens",
  "reset_at": "2026-11-01T04:00:00+00:00",
  "reset_in_seconds": 1296000
}

توجد تفاصيل كل حقل، وخيار الحد لكل مفتاح، وشيفرة المعالجة في الحصص وحدود معدل الطلبات.

أخطاء الخادم: 5xx

الحالة	الرمز	متى يحدث	ما الذي ينبغي فعله
500	`An internal error occurred. Please try again.`	عطل غير متوقع.	أعد المحاولة مرة بعد انتظار قصير.
500	`map_design_analyze_failed`	تعذّر على `POST /design/analyze` تحليل الجدول. لا تُحتسب تكلفة.	تحقّق من أعمدة الجدول وصفوف العينة ثم أعد المحاولة.
500	`Summary stream error`	تعذّر بدء `POST /chat/summary/stream` بسبب متن غير قابل للقراءة أو طلب مبنى بلا `address`. ويؤدي طول الحقل الزائد بدلًا من ذلك إلى 422 `field_too_long`.	صحّح المتن.
500	`Button chat stream error`	تعذّر بدء `POST /chat/button/stream` بسبب متن غير قابل للقراءة أو متن بلا `query`. ويؤدي طول الحقل الزائد بدلًا من ذلك إلى 422 `field_too_long`.	صحّح المتن.
503	`sessions_not_configured`	استبدال الجلسة غير متاح بسبب عطل في المنصة.	أعد المحاولة؛ تواصل مع الدعم إذا استمر العطل.
503	`share_grant_unavailable`	استبدال خريطة منشورة: تعذّر قراءة إعدادات الخريطة.	أعد المحاولة بعد قليل.

خطأ برمز الحالة 200

تعيد POST /chat/control/route الحالة 200 عندما يتعذر تخطيط مسار:

{ "error": "Route planning failed." }

تحتوي الاستجابة على error ولا تحتوي على action. سيعتبر العميل الذي يفحص الحالة وحدها ذلك نجاحًا، ثم يفشل عند قراءة action. تحقّق دائمًا من وجود error في المتن. صيغ النص ليُعرض للمستخدم مباشرة. التفاصيل: الاتجاهات.

تتصرف GET /retrieval/geocode/forward بصورة مشابهة: عند فشل البحث داخليًا تعيد 200 مع قائمة results فارغة، مثل استعلام لم يجد أي تطابق.

أخطاء البث المتدفق

ينطبق كل ما سبق قبل بدء البث: فالطلب المرفوض للبث يعيد خطأ HTTP عاديًا. وبعد أن تصبح الاستجابة 200 وتبدأ الإطارات بالتدفق، يظهر الفشل على هيئة حدث error:

event: error
data: {"type": "error", "code": "upstream_stall", "message": "The AI service stopped responding. Please try again.", "partial_text": "The Louvre sits"}

البث	`code`	متى يحدث	ما الذي ينبغي فعله
`/chat/control/stream`	`upstream_stall`	توقف توليد الإجابة عن التقدم، أو بلغ البث مدته القصوى البالغة نحو 10 دقائق.	اعرض إعادة المحاولة، واحتفظ بـ`partial_text` إذا كان مفيدًا.
`/chat/control/stream`	غير موجود	أي فشل آخر أثناء الإجابة.	اعرض `message`. قد تنجح المحاولة التالية.
`/chat/summary/stream`	غير موجود	فشل الملخص.	اعرض `message`، أو استمر دون ملخص.
`/spot/overview/stream`	غير موجود	فشل الوصف العام، أو يتعذر وصف `ref`. ويحمل الحدث `ref` عندما يتعذر وصفه: مرجع `poi:` أو `region:` لا يقع عند النقطة، أو `place:` دون `hint.name`، أو مبنى أو عنوان لا تصفهما الواجهة.	لا تعرض وصفًا عامًا. ولا تعِد محاولة حدث يحمل `ref`.
`/chat/button/stream`	لا يوجد	لا يرسل هذا البث حدث `error`. يغلق الفشل الاتصال دون `end`.	اعتبر أي بث يُغلق دون `end` فاشلًا.

قواعد تنطبق على جميع أنواع البث:

يحل حدث error محل end. ولا يتبعه إلا حدث quota اختياري، إن وجد.
يُعد الاتصال الذي يُغلق دون end أو error فاشلًا.
حدث quota ليس خطأً. إنه تقرير استخدام يُرسل بعد end أو error. وعند قراءة البث برمز جلسة، لا يحمل إلا type وmeter وreset_at.
اسم حدث غير معروف ليس خطأً؛ تجاهله.

يُحتسب البث الذي يفشل أو يُغلق قبل اكتماله. ولا تقل تكلفة /chat/control/stream عن تقدير لحجم المحادثة المرسلة، لذلك قد تزيد على الرصيد المحجوز عند البداية؛ راجع كيفية احتساب تكلفة البث. وإعادة المحاولة طلب جديد له تكلفة مستقلة.

الأخطاء التي يخفيها المتصفح

عندما يُرفض المصدر أو بيانات الاعتماد، لا تحتوي الاستجابة على ترويسة CORS، ويحجب المتصفح الحالة والمتن عن شيفرتك. تظهر للصفحة رسالة CORS في وحدة التحكم ويُرفض fetch؛ وتسجل حزمة التطوير خطأً يحوي [kaleidr:<product>].

لقراءة الرمز الحقيقي، افتح علامة Network واختر الطلب الفاشل. الرموز الشائعة هي origin_not_allowed وInvalid or missing API key وserver_key_in_browser. راجع CORS والمصادر المسموح بها.

تأتي استجابة 4xx التي لا تحتوي على متن Kaleidr بتنسيق JSON من حافة الشبكة قبل وصول الطلب إلى الواجهة. والسبب إما تحديد معدل الطلبات (خفّض المعدل ثم أعد المحاولة لاحقًا)، أو تجاوز الحجم المعلن للطلب حدود نقاط النهاية بمقدار كبير (أرسل بيانات أقل؛ فإعادة إرسال الطلب نفسه تنتج النتيجة نفسها).

مضيف مربعات الخرائط

تتلقى الطلبات إلى tile.kaleidr.com التي لا تأتي من تضمين Kaleidr بمفتاح قابل للنشر صالح ومن مصدر مسموح الاستجابة التالية:

الحالة	الرمز	`Retry-After`	ما الذي ينبغي فعله
429	`tile_access_restricted` (في `error` مع `message` و`docs`)	`3600`	استخدم منتج Tile بمفتاح قابل للنشر، وأضف مصدر الصفحة إلى قائمة مصادر المفتاح إذا كانت لديه قائمة.

إدارة المفاتيح

أخطاء https://api.kaleidr.com/shared-api/api-keys التي تستخدمها صفحة مفاتيح API ويمكنك استدعاؤها برمز وصول حسابك. تأتي جميعها بالشكل المغلّف.

الحالة	الرمز	متى يحدث	ما الذي ينبغي فعله
401	متنوع	لا يوجد رمز وصول صالح للحساب. لا يُقبل مفتاح منصة هنا.	سجّل الدخول مجددًا.
403	`org_admin_required`	حسابك ليس لمالك أو مسؤول في المؤسسة.	اسأل مالكًا أو مسؤولًا.
403	`plan_required`	لا توجد خطة للمؤسسة.	اختر خطة في kaleidr.com/billing.
403	`free_plan_publishable_only`	طُلب مفتاح خادم في خطة Free. ويُعاد أيضًا عند تدوير مفتاح خادم أو مفتاح قديم في Free.	أنشئ مفتاحًا قابلًا للنشر أو انتقل إلى Pro.
403	`tier_capability_not_allowed`	عند إنشاء مفتاح، يذكر `scopes` أو `allowed_products` ما لا تسمح به خطتك. عمليًا، هذا طلب نطاق `vendor` في Free أو Pro؛ ويُرفض سواء أُرسل `vendor_acknowledged` أم لا، ولا يُنشأ مفتاح. وعند تعديل المفتاح، يذكر `allowed_products` منتجًا لا تتضمنه الخطة، أو يُضبط على قائمة فارغة في Free.	يتطلب `vendor` خطة Enterprise. وإلا فاذكر نطاقات ومنتجات تسمح بها خطتك.
404	`key_not_found`	لا يوجد مفتاح بهذا المعرّف في المؤسسة. يتعرف التعديل والإلغاء على المفتاح مهما كانت حالته، لذا يُعيد إلغاء مفتاح ملغى مسبقًا 200. أما التدوير فيتطلب مفتاحًا نشطًا ويعيد هذا الرمز للمفتاح الملغى.	تحقّق من المعرّف. عند التدوير، قد يكون المفتاح ملغى.
409	`key_limit_reached`	بلغت المؤسسة حد مفاتيحها النشطة (Free 2، وPro 10، وEnterprise 25).	ألغِ مفتاحًا، أو دوّر مفتاحًا بدل إنشاء آخر.
409	`key_already_rotated`	دُوِّر المفتاح مسبقًا، سواء انتهت فترة السماح أم لا. لا يمكن تدويره مجددًا؛ ويُرفض تعديل يمسح `expires_at` أو يجعله بعد نهاية فترة السماح. ويظل تغيير `expires_at` إلى وقت أبكر وباقي الحقول مسموحًا.	استخدم المفتاح البديل.
409	`key_expired`	انقضت صلاحية مفتاح لم يُدوّر من قبل، ويشمل التعديل `expires_at`. لا يمكن منح المفتاح المنتهي صلاحية جديدة، لكن يمكن تعديل حقوله الأخرى.	أنشئ مفتاحًا جديدًا.
413	`request_body_too_large`	متن الطلب أكبر من 1 MiB.	أرسل متنًا أصغر.
422	`unknown_scope`	تحتوي `scopes` على قيمة غير `ai` أو `maps` أو `design` أو `vendor`.	صحّح القائمة.
422	`unknown_product`	تحتوي `allowed_products` على قيمة غير `chat` أو `editor` أو `viewer` أو `tile`.	صحّح القائمة.
422	`vendor_scope_requires_acknowledgement`	في Enterprise، طُلب مفتاح قابل للنشر يحمل `vendor` دون `vendor_acknowledged: true`. وفي Free وPro يُعاد للطلب نفسه 403 `tier_capability_not_allowed`.	اقرأ نطاق `vendor`، ثم أرسل الحقل.
422	`no_fields_to_update`	طلب تعديل لا يحوي أي حقل قابل للتعديل.	أرسل حقلًا واحدًا على الأقل.
422	قائمة تحقق	مصدر أو عنوان IP غير صالح، أو تاريخ انتهاء سابق، أو اسم غير صالح.	صحّح الحقل المذكور في `loc`.
500	`insert_failed`, `session_unavailable`	عطل في المنصة.	أعد المحاولة.
503	`api_key_pepper_not_configured`	إنشاء المفاتيح غير متاح بسبب عطل في المنصة.	أعد المحاولة، واتصل بالدعم إن استمر العطل.

تحميل بيانات الأعمال

أخطاء مسارات الرفع ضمن https://api.kaleidr.com/shared-api/datahub واستدعاء اقتراح المطابقة. توجد القائمة الكاملة، بما فيها حدود الملفات والحقول المسببة لكل 422، في رفع بيانات أعمالك. فيما يلي الأخطاء التي ترفض طلبًا قبل قراءة الملف، وأخطاء إلغاء نشر إصدار أو حذفه:

الحالة	الرمز	متى يحدث	ما الذي ينبغي فعله
403	`org_admin_required`	الحساب ليس لمالك أو مسؤول المؤسسة. ويُعاد أيضًا في طلب اقتراح المطابقة.	اسأل مالكًا أو مسؤولًا.
403	`vendor_data_not_on_plan`	خطة المؤسسة لا تسمح برفع بيانات الأعمال، فهي ميزة Enterprise فقط. يُعاد في الرفع والنشر وإعادة المعالجة واقتراح المطابقة، ولا يُعاد عند القراءة أو إلغاء النشر أو الحذف.	انتقل إلى Enterprise. تعيد `GET /shared-api/datahub/limits` ما إذا كانت المؤسسة تستطيع الرفع في كل الخطط دون رفض الطلب. في Free وPro، أضف البيانات إلى خريطة في Kaleidr Studio بدلًا من ذلك؛ راجع مجموعات البيانات على خريطة.
404	`release_not_found`	لا يوجد إصدار بالمعرّف المحدد في المؤسسة عند إلغاء النشر أو الحذف، بما في ذلك إصدار اكتمل حذفه.	عند الحذف، اعتبر العملية منجزة مسبقًا.
409	`org_ingest_in_progress`	تجري معالجة رفع آخر للمؤسسة. يُعاد في الرفع والنشر وإعادة المعالجة.	انتظر اكتماله ثم أعد الإرسال.
409	`release_not_published`	طُلب إلغاء نشر مسودة أو إصدار فاشل.	لا شيء لإلغاء نشره؛ احذفه بدلًا من ذلك.
409	`release_is_published`	طُلب حذف الإصدار المنشور.	ألغِ نشره ثم احذفه.
413	`request_body_too_large`	طلب الرفع أكبر من 32 MiB.	أرسل ملفًا أصغر. يمكن أن يصل حجم الملف نفسه إلى حد مؤسستك.
422	`{ "errors": [ … ] }` في `detail`	يتجاوز الملف حد الصفوف أو الحجم، أو يتجاوز حقل في حزمة JSON حد الطول، أو يكون تداخل JSON عميقًا جدًا. يذكر سبب الرفض للحد التعاقدي قيمة الحد والخطة.	اقرأ جميع الأسباب وصحّح الملف.
429	`ingest_rate_limited`	بدأت المؤسسة 30 عملية رفع خلال الساعة الماضية.	انتظر ثم أعد الإرسال.
429	جملة في `detail`	أجرى الحساب 30 اقتراح مطابقة خلال الساعة الماضية. لا يحتوي المتن على حقل `error`.	انتظر ثم أعد الإرسال.
429	`quota_exceeded` في `error`	اقتراح المطابقة: نفدت أرصدة الذكاء الاصطناعي للمؤسسة. المتن هو استجابة الحصة القياسية.	انتظر حتى `reset_at`، أو أضف أرصدة، أو اكتب المطابقة يدويًا.

تحميل مجموعات البيانات في Kaleidr Studio

لا ينتمي هذا القسم إلى واجهة المنصة المعتمدة على مفتاح API. بل يصف استجابة Kaleidr Studio عندما يضيف مستخدم مسجّل الدخول مجموعة بيانات إلى خريطة في لوحة Data ويُرفض الرفع بسبب الحجم. لا يُستخدم أي مفتاح API هنا. هناك نوعان مختلفان من الرفض:

الحالة	الرمز	متى يحدث	ما الذي ينبغي فعله
402	`quota_exceeded`	تجاوز رفع مجموعة بيانات جديدة أحد حدود خطة المؤسسة: صفوف مجموعة واحدة، أو حجم ملف واحد، أو مجموع الصفوف في كل مجموعات المؤسسة. يوضح `limit_key` الحد المرفوض. تبقى البيانات المخزنة مسبقًا. يعرض Studio رسالة مع رابط للترقية.	ارفع ملفًا أصغر أو احذف مجموعات لا تحتاجها. في Free انتقل إلى Pro. وفي Pro أو Enterprise، تواصل مع Kaleidr لزيادة إجمالي المؤسسة؛ ولا يمكن رفع حد الصفوف لمجموعة واحدة أو حجم الملف فوق السقوف في الصف التالي.
400	`VALIDATION_ERROR`	تجاوز الملف أو مجموعة البيانات سقفًا ينطبق على جميع الخطط: ملف أكبر من 64 MiB، أو مجموعة تزيد عن 100,000 صف، أو ملف جغرافي يزيد عن 50,000 معلم، أو صورة متراكبة أكبر من 16 MiB. يوجد الرمز في `error`. تغيير الخطة لا يسمح بالرفع.	قسّم الملف إلى ملفات أصغر. لا تعِد إرسال الملف نفسه ولا تعرض ترقية.

تتحدد الاستجابة بالحجم لا بالخطة وحدها. يُفحص السقف العام أولًا، لذلك يُعاد 400 في Free وPro وEnterprise جميعًا عند تجاوز الملف 64 MiB أو المجموعة 100,000 صف. أما 402 فلرفع ضمن السقف العام لكنه يتجاوز حد المؤسسة، مثل ملف حجمه 40 MiB في Free حيث الحد 32 MiB.

402 `quota_exceeded`

المتن كائن تفاصيل مشكلة يحمل أيضًا حقلي Studio error وmessage. يظهر الرمز في error وcode، وتظهر الجملة في message وdetail:

{
  "error": "quota_exceeded",
  "message": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "type": "https://errors.kaleidr.com/datasets/quota_exceeded",
  "title": "Quota Exceeded",
  "status": 402,
  "detail": "Your plan allows 250,000 rows across all of your organization's datasets. Delete a dataset or upgrade to add more.",
  "code": "quota_exceeded",
  "limit_key": "studio.data.rows.max",
  "limit": 250000,
  "used": 248500,
  "tier": "free",
  "upgrade_url": "https://kaleidr.com/pricing"
}

الحقل	المعنى
`error`, `code`	دائمًا `quota_exceeded`؛ القيمة نفسها مكررة.
`message`, `detail`	الجملة نفسها مكررة. تسمّي الحد بلغة واضحة وهي مخصصة لعرضها للمستخدم.
`type`	دائمًا `https://errors.kaleidr.com/datasets/quota_exceeded`.
`title`	دائمًا `Quota Exceeded`.
`status`	دائمًا `402`.
`limit_key`	الحد الذي منع الرفع. راجع الجدول التالي.
`limit`	حد المؤسسة بوحدة قياسه.
`used`	عند الحد الإجمالي: الصفوف المخزنة مسبقًا للمؤسسة. وللحدين الآخرين: عدد صفوف هذا الرفع أو حجمه بوحدة MiB.
`tier`	خطة المؤسسة: `free` أو `pro` أو `enterprise`. تكون `unknown` إذا تعذّرت قراءة الخطة؛ وعندها تسري حدود Free.
`upgrade_url`	عنوان تغيير الخطة.

`limit_key`	الحد	وحدة `limit` و`used`	الجملة
`studio.dataset.rows.max`	صفوف مجموعة بيانات واحدة	صفوف	«تسمح خطتك بـ50,000 صف في مجموعة بيانات واحدة. ارفع ملفًا أصغر أو رقِّ الخطة.»
`studio.dataset.file.mb`	حجم الملف الواحد المرفوع	MiB	«تسمح خطتك بملفات تصل إلى 32 MB. ارفع ملفًا أصغر أو رقِّ الخطة.»
`studio.data.rows.max`	الصفوف في جميع مجموعات المؤسسة	صفوف	«تسمح خطتك بـ250,000 صف في جميع مجموعات بيانات مؤسستك. احذف مجموعة بيانات أو رقِّ الخطة لإضافة المزيد.»

الأرقام المذكورة في الجمل تخص حدود Free؛ أما الجملة الفعلية التي تتلقاها فتحمل حدود مؤسستك. اعرضها للمستخدم وتفرّع برمجيًا حسب code وlimit_key. تختلف استجابة 402 هذه عن 429 quota_exceeded الصادرة عن واجهة المنصة الخاصة بأرصدة الذكاء الاصطناعي.

400 `VALIDATION_ERROR`

يتضمن المتن حقلين فقط دون أي أعضاء إضافية لتفاصيل المشكلة:

{
  "error": "VALIDATION_ERROR",
  "message": "File is larger than 64 MB."
}

سبب الرفض	`message`
ملف أكبر من 64 MiB	«الملف أكبر من 64 MB.»
مجموعة بيانات تزيد عن 100,000 صف	«الحد الأقصى 100000 سجل لكل مجموعة بيانات»
ملف جغرافي يزيد عن 50,000 معلم	«يحتوي `<filename>` على أكثر من 50000 معلم. قسّمه أو بسّط الشكل الهندسي قبل الرفع.»
صورة متراكبة أكبر من 16 MiB	«الصورة المتراكبة أكبر من 16 MB.»

تُعاد الحالة والرمز نفسيهما عند وجود مشكلات أخرى في الملف المرفوع، مثل نوع ملف لا يدعمه Studio أو ملف دون صفوف قابلة للاستخدام؛ وتوضح message السبب. تعامل مع كل 400 من عملية رفع بمعنى «لا يمكن إضافة هذا الملف بوضعه الحالي»، واعرض message.

موضوعات ذات صلة

المصادقة ونطاقات الصلاحية: بيانات الاعتماد واستبدال الجلسة.
الحصص وحدود معدل الطلبات: تفاصيل استجابات 429.
عقد SSE: أحداث البث.
استكشاف الأخطاء وإصلاحها: المشكلات وفق الأعراض.

أشكال الاستجابة​

المصادقة: 401​

التفويض: 403​

غير موجود: 404​

التحقق: 422​

حدود الطلبات: 422 مع رمز​

الطلب كبير جدًا: 413​

حدود الحصة ومعدل الطلبات: 429​

أخطاء الخادم: 5xx​

خطأ برمز الحالة 200​

أخطاء البث المتدفق​

الأخطاء التي يخفيها المتصفح​

مضيف مربعات الخرائط​

إدارة المفاتيح​

تحميل بيانات الأعمال​

تحميل مجموعات البيانات في Kaleidr Studio​

402 quota_exceeded​

400 VALIDATION_ERROR​

موضوعات ذات صلة​