رموز الأخطاء، ومخصّص المؤسسة، وسقوف الحجم، وسياسة إعادة محاولة محدودة. كل رقم ثابت في هذه الصفحة مقروء من إعدادات المنصة نفسها، لا من قاعدة تقريبية.
لكل إخفاق رمز ثابت. طابق على الرمز لا على نص الرسالة: فالرسائل مترجمة وقد تُعاد صياغتها، أما الرموز فهي العقد.
يستخدم الإخفاق الغلاف نفسه الذي تستخدمه الاستجابة الناجحة، مع ok بقيمة false ورمز يحدّد ما الذي حدث.
{
"ok": false,
"statusCode": 429,
"code": "ENTERPRISE_RUN_LIMIT_REACHED",
"message": "…",
"path": "/enterprise/v1/gis/buffer",
"method": "POST",
"timestamp": "2026-08-17T09:41:22.104Z"
}ENTERPRISE_API_KEY_REQUIREDوصل الطلب بلا بيانات اعتماد: لا زوج X-Api-Key و X-Api-Secret ولا ترويسة Authorization: Bearer.
أرسل بيانات الاعتماد مع كل استدعاء. وإذا نجح المفتاح نفسه من curl وفشل من عميلك، فتحقّق من أن العميل لا يحذف الترويسات المخصّصة عند إعادة التوجيه.
ENTERPRISE_API_KEY_INVALIDبيانات الاعتماد موجودة لكنها لم تُقبل — مفتاح عام غير معروف، أو مفتاح سري لا يطابق المخزّن له.
تأكد أنك نسخت المفتاح السري كاملًا عند إنشاء بيانات الاعتماد؛ فهو يُخزَّن مجزّأً ولا يمكن استرجاعه. وإن فُقد، فجدّد بيانات الاعتماد من تطبيقها في مركز التحكم واستخدم المفتاح السري الجديد.
ENTERPRISE_NOT_ACTIVEالمفتاح صالح، لكن المؤسسة التي يتبع لها معلّقة أو لم تعد نشطة.
لا شيء من جهتك يغيّر ذلك، وإعادة المحاولة تفشل بالطريقة نفسها. يتولّى الأمر مدير المؤسسة مع مكتب المؤسسات.
ENTERPRISE_API_NOT_IN_PLANفئة المؤسسة لا تشمل طلبات الواجهة البرمجية، فلا تستطيع مفاتيحها تشغيل الأدوات.
تأتي الواجهة البرمجية مع فئة المؤسسة؛ تواصل مع مكتب المؤسسات بشأن الفئة. ولن تفيد إعادة المحاولة.
ENTERPRISE_API_DAILY_LIMITاستنفدت المؤسسة طلبات الواجهة البرمجية لهذا اليوم — أي طلبات الفئة اليومية محسوبةً عبر جميع مفاتيحها.
انتظر حتى يتجدّد المخصّص عند منتصف الليل بالتوقيت العالمي. توزيع العمل على اليوم يجنّبك ذلك، أما إضافة مفاتيح فلا، لأن جميعها تسحب من المخصّص نفسه.
ENTERPRISE_RUN_LIMIT_REACHEDاستخدمت المؤسسة مرات تشغيل هذه الأداة في الفترة الحالية. ويجري التحقق قبل جدولة الأداة، فلم يُشغَّل شيء.
انتظر حتى تتجدّد الفترة: يعيد GET /usage وقت التجدّد، وكل استجابة ناجحة تحمله في usage.allowance.resetAt. ولكل أداة أخرى عدّادها الخاص.
كل رمز تربطه واجهات GIS والواجهة البرمجية بحالة HTTP.
الرموز أعلاه هي التي يُبنى عليها سلوك العميل. هذا الجدول مرجع لكل ما عداها، مجمّعًا حسب العائلة؛ والمعنى المعروض هو نص رسالة الواجهة نفسها. تعامل مع الرمز — فالرسائل مُعرّبة وقد تُعاد صياغتها.
لغة الرسالة
VALIDATION_ERRORخطأ في التحقق من البيانات.
FILE_REQUIREDالملف مطلوب.
FILE_TOO_LARGEحجم الملف يتجاوز الحد الأقصى المسموح به.
NOT_FOUNDغير موجود.
DUPLICATE_VALUEهذه القيمة موجودة بالفعل.
RATE_LIMIT_EXCEEDEDعدد كبير من الطلبات، حاول لاحقًا.
SERVER_ERRORحدث خطأ غير متوقع في الخادم.
GIS_INPUT_REJECTEDتعذّر استخدام هذا الملف: (reason)
GIS_PROCESSING_FAILEDفشلت معالجة GIS. يرجى التحقق من الملف والمحاولة مرة أخرى.
GIS_SERVICE_UNAVAILABLEخدمة معالجة GIS غير متاحة مؤقتاً. يرجى المحاولة لاحقاً.
GIS_BUSYمحرّك المعالجة مشغول الآن. لا مشكلة في ملفك — حاول مرة أخرى بعد قليل.
GIS_TIMEOUTاستغرقت العملية أكثر من المدة المسموح بها للطلب فأُوقفت. جرّب ملفًا أصغر، أو قسّم العمل إلى أجزاء.
GIS_TOOL_NOT_FOUNDأداة GIS غير معروفة.
GIS_TOOL_DISABLEDهذه الأداة معطّلة حالياً. يرجى المحاولة لاحقاً.
GIS_TIER_REQUIREDهذه الأداة متاحة ضمن عضوية أعلى.
GIS_ENTERPRISE_REQUIREDهذه الأداة متاحة في مساحات عمل المؤسسات.
GIS_NOT_COMMUNITY_MEMBERيجب أن تنضم إلى مجتمع حيز لاستخدام أدوات GIS.
GIS_USAGE_LIMIT_REACHEDلقد وصلت إلى الحد الأقصى لاستخدام هذه الأداة. سيتم تجديده تلقائياً.
GIS_FILE_NOT_FOUNDالملف الجغرافي المطلوب غير موجود.
ENTERPRISE_API_KEY_REQUIREDبيانات اعتماد الواجهة مطلوبة (X-Api-Key و X-Api-Secret).
ENTERPRISE_API_KEY_INVALIDبيانات اعتماد الواجهة غير صحيحة.
ENTERPRISE_API_KEY_EXPIREDانتهت صلاحية مفتاح الواجهة البرمجية هذا.
ENTERPRISE_API_KEY_INACTIVEمفتاح الواجهة البرمجية هذا غير نشط.
ENTERPRISE_API_KEY_IP_FORBIDDENالطلبات من عنوان IP هذا غير مسموح بها لهذا المفتاح.
ENTERPRISE_API_KEY_ORIGIN_FORBIDDENلا يُسمح بالطلبات من أصل المتصفح هذا لتطبيق هذا المفتاح.
ENTERPRISE_API_KEY_SCOPE_FORBIDDENلا يملك هذا المفتاح صلاحية الوصول إلى هذه الأداة.
ENTERPRISE_TOOL_NOT_ALLOWEDهذه الأداة غير مفعّلة لمؤسستك.
ENTERPRISE_NOT_ACTIVEهذه المؤسسة غير نشطة.
ENTERPRISE_API_NOT_IN_PLANلا تشمل فئة المؤسسة طلبات الواجهة البرمجية.
ENTERPRISE_API_DAILY_LIMITاستنفدت المؤسسة طلبات الواجهة البرمجية لهذا اليوم، وتتجدّد عند منتصف الليل بالتوقيت العالمي.
ENTERPRISE_RUN_LIMIT_REACHEDاستخدمت المؤسسة مرات تشغيل هذه الأداة لهذه الفترة، وتتجدّد عند بدء الفترة التالية.
ENTERPRISE_RATE_LIMIT_REACHEDطلبات كثيرة جدًا. الرجاء الإبطاء وإعادة المحاولة.
ENTERPRISE_CONCURRENCY_LIMIT_REACHEDعدد كبير من العمليات المتزامنة. الرجاء إعادة المحاولة بعد قليل.
ENTERPRISE_DATA_LIMIT_REACHEDتم استنفاد حد حجم البيانات للمؤسسة في هذه الفترة.
ENTERPRISE_IDEMPOTENCY_KEY_INVALIDترويسة Idempotency-Key غير صالحة (8–255 حرفًا قابلًا للطباعة).
IDEMPOTENCY_KEY_REUSEDاستُخدم مفتاح Idempotency-Key هذا مسبقًا مع طلب مختلف.
REQUEST_IN_PROGRESSما زال هناك طلب قيد المعالجة بمفتاح Idempotency-Key نفسه.
ENTERPRISE_RUN_NOT_FOUNDالعملية غير موجودة.
ENTERPRISE_ARTIFACT_NOT_FOUNDالملف الناتج غير موجود.
ENTERPRISE_ASYNC_JOB_NOT_FOUNDالمهمة غير موجودة.
ENTERPRISE_ASYNC_JOB_UPLOAD_NOT_FOUNDلم يُعثر على ملف مرفوع في موقع التخزين المؤقت بعد.
ENTERPRISE_ASYNC_JOB_ALREADY_FINALIZEDانتهت هذه المهمة بالفعل ولا يمكن تغييرها.
ENTERPRISE_ASYNC_TOOL_NOT_ELIGIBLEهذه الأداة لا تدعم المهام غير المتزامنة للملفات الكبيرة.
رموز مجموعات البيانات وروابط المشاركة وغرف البيانات موثقة مع دليل مجموعات البيانات في /docs/datasets.
ما يستطيع المفتاح تشغيله، محسوبًا لكل مؤسسة ولكل أداة، ومتى يتجدّد.
كل المفاتيح تتشارك مخصّصًا واحدًا
كم يستطيع الاستدعاء الواحد أن يحمل، وماذا يحدث حين يكون الملف أكبر من ذلك.
سقف الطلب المباشر
السقف غير المتزامن
نافذة الرفع
ما الذي يحدث للعمل الذي يُنفَّذ خارج الطلب، وسياسة إعادة المحاولة التي يُستحسن أن يحاكيها عميلك بدل أن يصارعها.
يُستجاب لطلب الإلغاء عند 4 نقاط تفتيش — لا فورًا.
عند الالتقاط
قبل أن يسحب العامل المهمة من الطابور أصلًا.
قبل حجز الحصة
قبل احتساب التشغيل من مخصّص المؤسسة.
قبل استدعاء المحرّك
بعد التهيئة، وقبل إرسال استدعاء المعالجة الجغرافية.
قبل تخزين المخرج
بعد عودة المحرّك، وقبل كتابة النتيجة وتسجيلها.
الاستدعاء الجاري ينتهي إلى آخره
نصف الدمج الجيد هو معرفة أي الإخفاقات دائم.
لا تعد المحاولة. بيانات الاعتماد ناقصة أو خاطئة، وتكرار الاستدعاء سيفشل بالطريقة نفسها. صحّح الترويسات ثم أرسل الطلب من جديد.
لا تعد المحاولة. فالمفتاح غير مسموح له بهذه الأداة، أو المؤسسة غير نشطة، أو فئتها لا تشمل الواجهة البرمجية — وكلٌّ منها يحتاج تغييرًا في مركز التحكم أو مع مكتب المؤسسات، لا محاولة أخرى.
أعد المحاولة بعد تجدّد المخصّص لا فورًا. ففي التشغيلات والطلبات اليومية يرد وقت التجدّد في الاستجابة وفي GET /usage، أما رفض الطلبات في الدقيقة أو التشغيلات المتزامنة فيزول خلال دقيقة، فتراجع قليلًا ثم أعد المحاولة.
أعد المحاولة مع تراجع تصاعدي وحدّ أقصى للمحاولات. ومحاكاة سياسة المنصة نفسها — 3 محاولات تبدأ من 2000 ms — خيار افتراضي معقول.
التشغيلات في الفترة الحالية — لكل مفتاح ولكل أداة — تظهر في صفحة الاستخدام لمؤسستك في مركز التحكم، ويعيدها GET /usage.