الأخطاء

تستخدم حالات فشل Platform API رموز حالة HTTP القياسية. تقريبًا كل حالة فشل تحمل سلسلة subcode مستقرة يجب على العملاء التفريع بناءً عليها — فرمز الحالة وحده غامض (403 يغطي scope والمنتج وorigin وIP ونوع المفتاح).

الغلاف

تعيد معظم الأخطاء غلاف detail بأسلوب FastAPI:

{ "detail": "<subcode>" }

حمولات 429 المنظمة (map_load_quota_exceeded, b2b_overloaded, org_overloaded, tile_access_restricted) هي كائنات مسطحة في المستوى الأعلى — دون غلاف detail:

{ "error": "map_load_quota_exceeded", "meter": "map_loads", "limit": 50000, "used": 50000 }

تحافظ أخطاء 429 ذات string-detail (map-load hard stops) على الغلاف:

{ "detail": "map_load_hard_stop" }

تبلغ بعض endpoints غير المتدفقة عن حالات الفشل كـ HTTP 200 مع مفتاح error — وأبرزها POST /chat/control/route. أي عميل يعتمد على status فقط سيتعامل معها كنجاح. اقرأ body دائمًا.

الجدول

الحالة	Subcode	المعنى	ما الذي يجب فعله
401	(no detail)	مفتاح مفقود / غير صالح / ملغى / منتهي	تحقق من قيمة المفتاح وأنه غير ملغى. Viewer لا يحتاج إلى مفتاح.
401	publishable_requires_session	تم إرسال مفتاح publishable (kld_pk_…) كـ bearer مباشر	استخدمه عبر SDK الذي يبدله بجلسة.
403	insufficient_scope	مفتاح صالح لكنه يفتقر إلى scope الخاص بالمسار	أنشئ / أعد إنشاء مفتاح بالـ scope الصحيح (ai / maps / design).
403	tier_capability_not_allowed	المفتاح المخزن كان يملك الإمكانية، لكن الخطة الحالية للمؤسسة لم تعد تسمح بها (عادةً تخفيض Pro→Free)	قم بترقية الخطة، أو استخدم منتجًا تسمح به الخطة الحالية.
403	origin_required	تم استخدام مفتاح publishable دون Origin للمتصفح (مثل الاستخدام من الخادم)	مفاتيح publishable للمتصفح فقط.
403	session_origin_mismatch	Origin الخاص بالطلب غير موجود في allowlist الخاصة بالمفتاح	حدّث allowed origins على المفتاح (راجع الحصول على مفتاح API).
403	product_not_allowed	المفتاح غير مسموح له باستخدام هذا المنتج	أنشئ مفتاحًا يسمح بهذا المنتج (أو استخدم viewer، فهو لا يحتاج إلى مفتاح).
403	server_key_in_browser	تم استخدام server key (kld_sk_…) من المتصفح	مفاتيح server للخادم فقط؛ كما أنها محظورة عبر CORS.
403	ip_not_allowed	تم استخدام server key من IP خارج allowlist الخاصة به	حدّث IP allowlist للمفتاح أو أرسل الطلب من عنوان مسموح.
403	publishable_key_required	تمت محاولة SDK session exchange باستخدام شيء غير مفتاح publishable	استخدم مفتاح kld_pk_… في خطوة session-exchange.
403	sessions_disabled	إصدار الجلسات معطل لهذا deployment	تواصل مع الدعم — هذه حالة تشغيلية وليست إعدادًا للعميل.
403	sessions_not_configured	بنية الجلسات غير مهيأة	تواصل مع الدعم.
422	(various)	body للطلب غير صحيح البنية	أصلح payload (راجع Endpoints). عند mint، تعني unknown_scope / unknown_product قيمة غير معروفة؛ ويعني publishable_live_requires_origins أنه تم إنشاء مفتاح publishable حي دون allowed origins.
429	(flat) map_load_quota_exceeded	تم استهلاك الحصة الشهرية لتحميلات الخرائط لدى المؤسسة	قم بالترقية أو قلل تحميلات basemap.
429	map_load_hard_stop	المؤسسة المدفوعة تجاوزت حصة map-loads بمقدار 5×	يتوقف التقديم هنا؛ أما النطاق المرن فوق الحصة فيستمر في العمل.
429	(flat) tile_access_restricted	تم رفض طلب Tile (غالبًا بسبب فقدان origin من allowlist). يحمل Retry-After: 3600	أضف origin الصفحة إلى allowlist الخاصة بالمفتاح؛ وأعد المحاولة بعد المدة الموجودة في header.
429	(flat) b2b_overloaded	يتم تطبيق global request-shedding	تراجع وأعد المحاولة مع jitter.
429	(flat) org_overloaded	request shedding على مستوى المؤسسة	تراجع وأعد المحاولة.
429	limiter_unavailable	rate limiter غير متاح مؤقتًا	تعامل معه كحالة مؤقتة؛ أعد المحاولة.
429	rate_limited	عدد كبير جدًا من الطلبات حاليًا	احترم Retry-After.
503	(no detail)	خدمة المفاتيح غير متاحة مؤقتًا	مؤقت — أعد المحاولة قريبًا.

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

حالات الفشل من POST/PATCH/DELETE /shared-api/api-keys/* (باستخدام Cognito org-admin JWT، وليس platform key):

الحالة	Subcode	المعنى
403	free_plan_publishable_only	المؤسسات على خطة Free يمكنها إنشاء مفاتيح publishable فقط.
403	plan_required	لا يوجد لدى المؤسسة صف API plan معروف.
403	tier_capability_not_allowed	حاول PATCH توسيع مفتاح إلى ما يتجاوز ما تسمح به الخطة الحالية للمؤسسة.
403	vendor_scope_requires_acknowledgement	يتطلب scope vendor علامة إقرار صريحة لكل مفتاح.
409	key_limit_reached	وصلت المؤسسة إلى الحد الأقصى لعدد المفاتيح لكل مؤسسة في خطتها.

راجع الحصول على مفتاح API لمعرفة عملية mint الكاملة ومسار تحديث PATCH.

أخطاء البث

في SSE stream، يصل الفشل النهائي كحدث error بدلًا من HTTP status (لأن الاستجابة بدأت بالفعل بـ 200):

event: error
data: { "type":"error", "message":"…", "code":"…", "partial_text":"…" }

تعامل مع حدث error كنهاية لذلك stream. أما حدث quota أثناء البث فـ ليس خطأ — بل هو العداد الذي يخبرك بكمية الميزانية المتبقية. يجب على العملاء تجاهل أسماء الأحداث غير المعروفة — فقد تتم إضافة أحداث جديدة ضمن العقد المستقر دون تحديث الإصدار.

CORS "محظور" في المتصفح

إذا أبلغ المتصفح عن حظر CORS في طلب حقيقي، فإن Origin الخاص بالطلب غير موجود في allowlist الخاصة بالمفتاح — وليست مشكلة auth. راجع CORS & allowed origins.