الحصص وحدود المعدل

فاتورة واحدة لكل مؤسسة

يتم قياس استخدام Platform لكل مؤسسة، وليس لكل مفتاح — فجميع مفاتيح مؤسستك تستهلك من ميزانية شهرية مشتركة واحدة وتخضع لـ rate-limit معًا. مفتاح واحد، فاتورة واحدة: AI وmaps وdesign كلها تخصم من org meter نفسه.

تُعاد الميزانية على دورة تقويمية شهرية.

ما تتضمنه خطتك

تحدد خطة مؤسستك ما يمكن للمفتاح الوصول إليه وكذلك monthly token budget المشتركة:

Plan	API surface	Monthly API tokens	Monthly map loads
Free	Basemaps فقط — publishable key بنطاق maps ومنتج tile	n/a (لا يوجد نطاق ai)	50,000
Pro	platform كاملة (ai, maps, design; browser + server keys)	5,000,000	50,000
Enterprise	platform كاملة	50,000,000	50,000

جميع الخطط تحمل map-loads allowance نفسها — وتختلف الخطط حسب tokens وAPI surface والميزات. أما أحجام Enterprise فوق allowance فيتم منحها كزيادات لكل مؤسسة، وليست plan rung أكبر.

تقدم مفاتيح خطة Free basemap embeds، ويتم قياسها كـ map loads بدلًا من tokens. وللوصول إلى AI وdesign surfaces، قم بالترقية عبر kaleidr.com/billing. تسري تغييرات الخطة على المفاتيح الحالية خلال بضع دقائق؛ ولا حاجة إلى re-mint — رغم أن المفتاح الذي تم mint له في Free تتم إعادة scope له عند rotate التالية.

Body الخاص بـ 429

يعيد request الذي سيتجاوز الحد 429 Too Many Requests مع flat top-level body — ولا تقوم structured 429 payloads بتغليف الحقول داخل كائن detail (فقط 429 ذات string-detail مثل map_load_hard_stop تفعل ذلك):

{
  "error": "b2b.tokens_exceeded",
  "meter": "b2b.tokens",
  "tier": "pro",
  "limit": 5000000,
  "used": 5000000,
  "remaining": 0,
  "reset_at": "2026-10-01T00:00:00Z",
  "reset_in_seconds": 123456
}

بالنسبة إلى streaming endpoints، يظهر الحد أيضًا أثناء stream عبر quota SSE event لكي تستطيع UI الاستجابة قبل انتهاء stream.

راجع Errors — Envelope للاطلاع على التقسيم الكامل بين flat 429s والأنواع المغلفة.

تجاوز allowance

ما يحدث عند تجاوز allowance يعتمد على خطتك، والحالتان مختلفتان عمدًا.

Free تتوقف عند allowance. أي request سيتجاوزها يعيد 429 map_load_quota_exceeded. وهذا الحد هو free basemap product.

Pro وEnterprise تستمران في الخدمة. فالـ overage في الحساب المدفوع هو موضوع billing وليس outage، ولذلك لا تختفي embeds في منتصف الشهر — بل نسجل overage ونتابع معك.

لكن هذا التساهل ليس بلا حدود. تتوقف الخطط المدفوعة عند خمسة أضعاف allowance باستخدام 429 map_load_hard_stop. لا يصل embed طبيعي إلى هذا الحد؛ فالحد الأقصى موجود حتى لا يتمكن شخص نسخ publishable key من page source من إنشاء فاتورة غير محدودة باسمك. وترفع purchased map-load packs قيمة allowance، كما يرتفع ceiling معها.

إذا كنت تصل إلى soft band بانتظام، فأنت بحاجة إلى allowance أكبر بدلًا من حل التفافي — تواصل معنا.

الوصول إلى Basemap

تعد designed basemaps جزءًا من حساب Kaleidr الخاص بك، وليست standalone public tile API: تقوم <kaleidr-map> embeds وSDK بالتصريح من خلال publishable key (maps scope)، وكل map load — سواء فتح shared-map أو published/embedded view أو SDK basemap session، بما يقارب 20 tile requests — يستهلك من monthly allowance المشتركة المذكورة أعلاه. ويتم حظر الاستخدام المباشر من طرف ثالث لـ tile.kaleidr.com خارج keyed embed باستخدام 429 وهذا body:

{
  "error": "tile_access_restricted",
  "message": "Direct access to tile.kaleidr.com requires a Kaleidr account. Kaleidr-hosted maps and embeds are unaffected — see the docs.",
  "docs": "https://docs.kaleidr.com/platform-api/quota-and-rate-limits"
}

يحمل 429 أيضًا header باسم Retry-After: 3600 — لا تعاود المحاولة قبل ذلك.

إذا كنت تحتاج إلى أكثر من allowance، تواصل معنا — يتم منح الأحجام الأعلى لكل مؤسسة، ويمكن لـ Enterprise التقديم من CDN مستقل.

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

يوجد حدان أمام quota، وكلاهما يسقط الحمل الزائد باستخدام 429 بدلًا من وضعه في queue:

• Requests per minute, per key — نافذة متحركة مدتها 60 ثانية. يحمل كل مفتاح rate خاصًا به.
• Concurrent streams, per organization — streaming requests متزامنة عبر جميع مفاتيح المؤسسة.

أعد المحاولة باستخدام backoff. 429 هنا تعني "السرعة عالية جدًا الآن"؛ أما 429 التي تحمل meter داخل body فتعني أنك وصلت إلى monthly cap (أعلاه).

كيفية التعامل معها

• تعامل مع 429 على أنها "أبطئ / قم بالترقية" وليس "تعطل". استخدم backoff وأعد المحاولة.
• اعرض quota event أثناء stream في UI (الميزانية المتبقية).
• راجع Errors للاطلاع على جدول status الكامل.