الحصص وحدود معدّل الطلبات

يقيّد Kaleidr الاستخدام بطريقتين مختلفتين، وتُرجع كلتاهما حالة HTTP 429:

الحصة هي مقدار الاستخدام المتاح لمؤسستك خلال فترة فوترة واحدة. وإذا نفدت، فعليك الانتظار حتى تتجدد الفترة أو إضافة سعة أخرى.
حدود معدّل الطلبات تحدد سرعة إرسال الاستدعاءات. وعند بلوغ أحد الحدود، ينبغي إبطاء الطلبات لبضع ثوانٍ.

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

رصيدا الاستخدام

يُحتسب الاستخدام على مستوى المؤسسة ضمن رصيدين منفصلين.

الرصيد	العمليات التي تستهلكه	Free	Pro	Enterprise
أرصدة الذكاء الاصطناعي	إجابات الدردشة، واستعلامات الأماكن، والبحث عن العناوين، وتحليل التصميم	500,000 لكل فترة	5,000,000 لكل فترة	مخصص وفقًا للعقد
مرات تحميل الخرائط	كل جلسة Tile وكل مشاهدة لخريطة منشورة أو مضمّنة	50,000 لكل فترة	50,000 لكل فترة	نفس الرصيد الأساسي، وتحدد الكميات الأكبر في العقد

هناك ثلاث نقاط يسهل إساءة فهمها بشأن هذين الرصيدين:

أرصدة الذكاء الاصطناعي مشتركة على مستوى المؤسسة كلها. تستهلك مفاتيح API الأرصدة نفسها التي يستخدمها فريقك داخل تطبيقات Kaleidr. ولا توجد ميزانية منفصلة للواجهة، إذ تشترك جميع المفاتيح في الرصيد ذاته.
الفترة هي فترة الفوترة الخاصة بك. في الاشتراكات المدفوعة، تكون دورة شهرية تبدأ من يوم الاشتراك. ومن دون اشتراك تُعتمد الأشهر التقويمية. تتجدد الفترات عند منتصف الليل بتوقيت شرق الولايات المتحدة.
الباقات الإضافية ترفع الحد. تُضاف باقات أرصدة الذكاء الاصطناعي ومرات تحميل الخرائط المشتراة إلى مخصصات الخطة، ويتضمنها الحقل limit في الاستجابات.

تُطبّق تغييرات الخطة على مفاتيحك الحالية خلال دقائق، ولا تحتاج إلى إنشاء مفاتيح جديدة.

الرسوم المترتبة على كل استدعاء

الاستدعاء	الرصيد	الرسوم
`POST /chat/control/stream`, `/chat/summary/stream`, `/chat/button/stream`, `/spot/overview/stream`	أرصدة الذكاء الاصطناعي	عدد الرموز المستخدمة في الإجابة، بما في ذلك المدخلات والمخرجات. راجع كيفية احتساب تكلفة البث.
`POST /chat/control/route`	لا شيء	بلا رسوم. يُحجز مقدار مؤقت أثناء تخطيط المسار، ثم يُحرر دائمًا.
`POST /spot`	أرصدة الذكاء الاصطناعي	رسم ثابت لكل استدعاء، سواء وُجدت نتائج أم لا: يُطبق رسم `/retrieval/poi/enrich` عندما تتضمن `want` القيمة `content` أو `photos` ويُجلب المحتوى لهذا الاستدعاء، وإلا فيُطبق رسم `/retrieval/geocode/forward` عندما تتضمن `address`. والمحتوى الذي جُلب لطلب سابق لا يكلف شيئًا. أما الاستدعاء الذي يطلب الأماكن والمناطق والحدود فقط فهو مجاني.
`GET /retrieval/poi/enrich`	أرصدة الذكاء الاصطناعي	رسم ثابت لكل استدعاء، حتى إذا لم يُعثر على محتوى.
`GET /retrieval/geocode/forward`	أرصدة الذكاء الاصطناعي	رسم ثابت أقل لكل استدعاء، حتى إذا لم توجد نتائج. ولا تُحتسب رسوم إذا فشل البحث نفسه.
`POST /design/analyze`	أرصدة الذكاء الاصطناعي	رسم ثابت لكل استدعاء ناجح، ولا تُفرض رسوم عند فشله.
`POST /design/apply-direct`, `GET /design/styles`, `/design/samples`, `/design/themes`	لا شيء	بلا رسوم.
`POST /sdk/sessions` للمنتجات `chat` و`editor` و`viewer`	لا شيء	بلا رسوم.
`POST /sdk/sessions` للمنتج `tile`	مرات تحميل الخرائط	تُحتسب مرة تحميل خريطة واحدة لكل عملية تبادل.
`POST /sdk/share-sessions`	لا شيء	بلا رسوم. وتُحتسب استدعاءات الدردشة عبر الجلسة على حساب مالك الخريطة.
`POST /inference-api/vendor/mapping/propose`، أي اقتراح تعيين الحقول في واجهة تحميل بيانات الأعمال	أرصدة الذكاء الاصطناعي	عدد الرموز المستخدمة لإنشاء الاقتراح. يُستدعى باستخدام تسجيل الدخول إلى الحساب، لا بمفتاح API. وعند نفاد الأرصدة يُرجع 429 `quota_exceeded`؛ وله أيضًا حد مستقل يبلغ 30 اقتراحًا لكل حساب في الساعة، ويختلف نص الاستجابة بين حالتي 429. لا رسوم على التحميل أو النشر أو إلغاء النشر أو الحذف.

يمكنك الاطلاع على الاستخدام الحالي والحدود في kaleidr.com/billing.

كيفية احتساب تكلفة البث

لا تُعرف التكلفة الفعلية لاستدعاء البث إلا عند انتهائه، لذلك تُحتسب على مرحلتين:

الحجز. عند قبول الطلب، يُحجز عدد ثابت من الأرصدة من الرصيد المتاح. إذا لم يكفِ الرصيد للحجز، يُرفض الطلب مع quota_exceeded قبل إنشاء أي إجابة. وهذا يعني أن بدء الاستدعاء يتطلب هامشًا كافيًا من الأرصدة حتى إن كانت تكلفته الفعلية أقل.
التسوية. عند انتهاء البث، يُستبدل المبلغ المحجوز بالتكلفة الفعلية، وهي عدد الرموز المستخدمة في الإجابة. وقد تكون التكلفة الفعلية أعلى من المبلغ المحجوز أو أقل منه.

إذا أوقفت البث أو فشل قبل اكتمال الإجابة، فلن يكون عدد الرموز معروفًا بدقة وستُحسب الرسوم بالتقدير:

البث	الرسوم عند انتهائه دون اكتمال
`/chat/control/stream`	القيمة الأكبر من تقدير حجم المحادثة التي أرسلتها (رسائل `user` و`assistant` في الطلب)، أو تقدير النص الذي بُث بالفعل، ويُحسب الأخير حتى مبلغ الحجز. قد تتجاوز التكلفة مبلغ الحجز.
`/chat/summary/stream`, `/chat/button/stream`, `/spot/overview/stream`	تقدير للنص الذي بُث بالفعل، ولا يتجاوز مبلغ الحجز مطلقًا.

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

بلوغ الحد أثناء تشغيل بث لا يوقف ذلك البث. يُجرى التحقق عند قبول الطلب، ويُرفض الطلب التالي.

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

سقف استهلاك لمفتاح واحد

يمكن تعيين سقف شهري للمفتاح (monthly_cap_tokens، عبر واجهة إدارة المفاتيح). ويحد هذا السقف مقدار ما يستهلكه المفتاح من أرصدة الذكاء الاصطناعي الخاصة بالمؤسسة خلال فترة واحدة. ويظل الرصيد الإجمالي للمؤسسة هو الحد الأعلى.

إذا كان الطلب سيؤدي إلى تجاوز سقف مفتاح معيّن، فسيُرفض باستخدام الاستجابة نفسها quota_exceeded، لكن limit وused سيعرضان أرقام المفتاح بدلًا من أرقام الرصيد الإجمالي.

تجاوز الحصة

HTTP/1.1 429 Too Many Requests
Retry-After: 1296000
Content-Type: application/json

{
  "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`	جملة موجهة للمستخدم. لا تحللها برمجيًا.
`product`, `meter`	يحددان عدّاد أرصدة الذكاء الاصطناعي في واجهة API. وتكون قيمتاهما دائمًا `b2b` و`b2b.tokens` لمفاتيح المنصة.
`tier`	خطة مؤسستك.
`limit`, `used`, `remaining`	قيم رصيد المجموعة، أو قيم المفتاح عند رفض الطلب بسبب حد خاص بالمفتاح. قد تكون قيمة `remaining` أكبر من الصفر، لأن الطلب رُفض لعدم كفاية الرصيد لتغطية الحجز المؤقت.
`reset_at`	نهاية الفترة، على هيئة طابع زمني وفق ISO 8601 يتضمن إزاحة المنطقة الزمنية. استخدم هذه القيمة لإبلاغ المستخدم بموعد استئناف الخدمة.
`period`	`month`.
`reset_in_seconds`	عدد الثواني المتبقية حتى `reset_at`، أي نهاية الفترة التي يُعاد عندها ضبط رصيدك (دورة اشتراكك، أو الشهر الميلادي في غياب اشتراك). تحمل ترويسة `Retry-After` العدد نفسه.

نص الاستجابة مسطح: تقع الحقول في المستوى الأعلى، وليس داخل كائن detail.

عند استخدام رمز جلسة

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

{
  "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
}

الحقل	مفتاح خادم أو مفتاح قديم	رمز جلسة
`error`, `detail`	نعم	نعم
`meter`	نعم	نعم
`reset_at`, `reset_in_seconds`	نعم	نعم
`product`, `period`	نعم	لا
`tier`	نعم	لا
`limit`, `used`, `remaining`	نعم	لا

تبقى الحالة وترويسة Retry-After والمعنى كما هي. في شيفرة المتصفح، افحص error واعرض reset_at؛ ولا تحاول قراءة limit أو used أو remaining. لعرض أرقام الاستخدام، اقرأها من خادمك باستخدام مفتاح خادم أو من kaleidr.com/billing.

إذا عرضت الاستجابة used: 0 رغم معرفتك بأن المؤسسة كانت نشطة، فهذا يعني أن الواجهة لم تستطع قراءة الاستهلاك فرفضت الطلب احتياطيًا. أعد المحاولة بعد ثوانٍ بدلًا من الانتظار حتى reset_at.

حدود المعدّل والتزامن

تُطبَّق ثلاثة حدود قبل كل استدعاء أثناء التشغيل. ويُرفض أي طلب يتجاوزها فورًا، دون وضعه في قائمة انتظار.

الحد	وحدة الاحتساب	النطاق
الطلبات في الدقيقة	المفتاح	نافذة متحركة مدتها 60 ثانية تشمل كل استدعاء أثناء التشغيل بالمفتاح وبكل جلسة مستخرجة منه. ويتشارك جميع زوار موقع يستخدم مفتاحًا واحدًا قابلًا للنشر هذه الحصة.
عمليات تبادل الجلسات في الدقيقة	المفتاح	استدعاءات `POST /sdk/sessions`. ولها حصة مستقلة، لذا لا يستهلك تضمين المكونات حصة استدعاءات التشغيل.
الطلبات المتزامنة	المؤسسة	جميع الاستدعاءات الجارية في اللحظة نفسها عبر كل مفاتيح المؤسسة. ويُحتسب البث طوال بقائه مفتوحًا.

لا يمكن تعديل حد الطلبات في الدقيقة لمفتاح عبر صفحة مفاتيح API أو واجهة إدارة المفاتيح. إذا احتجت إلى معدل أعلى، فتواصل معنا.

تستخدم جميع حالات الرفض هذه البنية نفسها وترويسة الاستجابة نفسها:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{ "error": "rate_limited", "detail": "API key rate limit exceeded. Slow down." }

`error`	المعنى	الإجراء المطلوب
`rate_limited`	استُنفدت حصة المفتاح من الطلبات في الدقيقة أو عمليات تبادل الجلسات.	انتظر عدد الثواني في `Retry-After` ثم أعد المحاولة مع إضافة تأخير عشوائي.
`org_overloaded`	لدى مؤسستك عدد كبير جدًا من الاستدعاءات الجارية.	انتظر حتى ينتهي أحد الاستدعاءات المفتوحة ثم أعد المحاولة. وأغلق البثوث غير الضرورية.
`b2b_overloaded`	بلغت واجهة API طاقتها القصوى لكل المستدعين.	انتظر مدة `Retry-After` ثم أعد المحاولة بتأخير متزايد.
`limiter_unavailable`	لم تتمكن خدمة تحديد المعدل من الاستجابة.	أعد المحاولة بعد قليل. لن يفيد إبطاء الطلبات لأن المشكلة ليست في معدل استخدامك.
`visitor_limit_reached`	تجاوز أحد زوار دردشة خريطة منشورة حد الطلبات في الدقيقة أو اليوم.	اعرض رسالة تطلب من الزائر المحاولة لاحقًا. راجع الدردشة على خريطة منشورة.

تُطبَّق حدود للمعدل أيضًا عند حافة الشبكة بحسب عنوان IP وبيانات الاعتماد. والطلبات المحظورة هناك لا تتضمن أيًا من أجسام JSON الواردة في هذه الصفحة. تعامل مع استجابة 4xx التي لا تحتوي على نص استجابة من Kaleidr بوصفها إشارة إلى الإبطاء وإعادة المحاولة لاحقًا.

مرات تحميل الخرائط

تُحتسب مرة تحميل للخريطة كلما بدأ تشغيل خريطة Kaleidr لأحد الزوار:

كل عملية تبادل جلسة للمنتج product: "tile"، بما في ذلك تجديد SDK وإعادة تركيب العنصر؛
كل عرض لخريطة منشورة أو مضمنة.

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

تتوقف جميع الخطط عند حصتها المسموح بها. عندما ينفد الرصيد تُرفض عملية التحميل التالية ولا تُحتسب. ولا توجد فترة سماح للخطط المدفوعة؛ ويؤدي شراء حزمة تحميل الخرائط إلى رفع الحد فورًا.

تأتي استجابة الرفض في عملية تبادل الجلسة بالشكل التالي:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{ "detail": "map_load_quota_exceeded" }

يأتي هذا النص داخل detail، بخلاف نص الحصة المسطح أعلاه، ولا يتضمن ترويسة Retry-After. لن تفيد إعادة المحاولة حتى تتجدد الفترة أو تضيف حزمة. على الصفحة يفشل تضمين Tile في البدء، ويسجل SDK الرسالة kaleidr session exchange failed (429).

طلبات البلاطات المباشرة

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

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Cache-Control: no-store
Content-Type: application/json

{
  "error": "tile_access_restricted",
  "message": "Direct access to tile.kaleidr.com requires a Kaleidr publishable key. Mint a free one at kaleidr.com/api-keys and pass it as ?key= from an allowed origin. Kaleidr-hosted maps and embeds are unaffected.",
  "docs": "https://docs.kaleidr.com/get-an-api-key"
}

تأتي هذه الاستجابة من مضيف البلاطات، لا من واجهة المنصة؛ لذا تستخدم message حيث تستخدم الواجهة detail. وقد يستغرق قبول المفتاح الجديد أو المعدَّل للبلاطات بضع دقائق.

حدث `quota` في البث

يُبلغ بث الدردشة عن الرصيد بعد احتساب الرسوم. ويكون حدث quota هو الحدث الأخير في البث، ويُرسل بعد end أو error:

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

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

event: quota
data: {"type": "quota", "meter": "b2b.tokens", "reset_at": "2026-11-01T04:00:00+00:00"}

الحقل	مفتاح خادم أو مفتاح قديم	رمز جلسة
`type`, `meter`, `reset_at`	نعم	نعم
`product`, `period`	نعم	لا
`tier`	نعم	لا
`used`, `limit`	نعم	لا

باستخدام مفتاح خادم، يمكنك تحديث مقياس الاستخدام من هذا الحدث دون طلب ثانٍ. وتنطبق ثلاثة قيود:

لا يحتوي على الحقل remaining. احسب limit - used.
يُرسل الحدث على أساس بذل أقصى جهد؛ وقد ينتهي البث دونه، لذلك لا تنتظره.
الحدث للإبلاغ وليس للتحذير المسبق. ولا يصل أثناء الإجابة ولا يستطيع إيقاف البث.

للحصول عليه، واصل القراءة حتى يُغلق نص الاستجابة. فالعميل الذي يتوقف عند end سيفوته هذا الحدث.

معالجة 429 في الشيفرة

اقرأ نص الاستجابة قبل اتخاذ القرار. فلا تكفي الحالة وحدها لمعرفة ما إذا كان ينبغي إعادة المحاولة.

الاستجابة المستلمة	هل تُعاد المحاولة؟	متى؟
`error: "quota_exceeded"`	لا	بعد `reset_at`، أو بعد إضافة أرصدة أو رفع سقف المفتاح. اعرض للمستخدم رسالة تفيد ببلوغ الحد.
`error: "rate_limited"`, `"org_overloaded"`, `"b2b_overloaded"`, `"limiter_unavailable"`	نعم	بعد ثواني `Retry-After` مع تأخير عشوائي، وبحد أقصى بضع محاولات.
`error: "visitor_limit_reached"`	لا	لاحقًا؛ أبلغ الزائر بذلك.
`detail: "map_load_quota_exceeded"`	لا	بعد تجدد الفترة أو إضافة حزمة لتحميل الخرائط.
`error: "tile_access_restricted"`	لا	أصلح التضمين: استخدم منتج Tile بمفتاح قابل للنشر على أصل مسموح به.

const RETRYABLE = new Set(['rate_limited', 'org_overloaded', 'b2b_overloaded', 'limiter_unavailable']);

async function callKaleidr(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status !== 429) return res;

  const body = await res.json().catch(() => ({}));
  if (RETRYABLE.has(body.error) && attempt < 3) {
    const seconds = Number(res.headers.get('retry-after')) || 5;
    await new Promise((resolve) => setTimeout(resolve, (seconds + Math.random()) * 1000));
    return callKaleidr(url, init, attempt + 1);
  }

  const error = new Error(body.error || body.detail || 'rate limited');
  error.status = 429;
  error.code = body.error || body.detail;
  error.resetAt = body.reset_at; // present for quota_exceeded
  throw error;
}

يمكن لشيفرة JavaScript في المتصفح قراءة ترويسة Retry-After من استجابات واجهة API للمنصة.

صفحات ذات صلة

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

رصيدا الاستخدام​

الرسوم المترتبة على كل استدعاء​

كيفية احتساب تكلفة البث​

سقف استهلاك لمفتاح واحد​

تجاوز الحصة​

عند استخدام رمز جلسة​

حدود المعدّل والتزامن​

مرات تحميل الخرائط​

طلبات البلاطات المباشرة​

حدث quota في البث​

معالجة 429 في الشيفرة​

صفحات ذات صلة​