رسائل الخطأ

توضّح هذه الصفحة رسائل الخطأ التي يمكن أن تعرضها Maps JavaScript API. تكتب Maps JavaScript API رسائل الخطأ والتحذير في وحدة تحكّم JavaScript. قد تحدث أيضًا بعض حالات الخطأ التي تؤدي إلى عرض خريطة معتمة عليها علامة مائية.

أخطاء مفتاح واجهة برمجة التطبيقات والفوترة

تحديد المشاكل وحلّها

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

ستساعدك سلسلة الخطوات التالية في تحديد المشكلة وحلّها.

رموز الخطأ في Maps JavaScript API للمطوّرين ومالكي المواقع الإلكترونية

تعرض الجداول التالية رموز الأخطاء المحتملة التي يعرضها Maps JavaScript API، مع وصف للسبب وكيفية حل المشكلة. للحصول على مساعدة بشأن العثور على رسائل الخطأ، يُرجى الاطّلاع على القسم الخاص بالتحقّق من الأخطاء في المتصفّح.

أخطاء تحميل الخريطة

إذا واجهت خطأ أثناء تحميل Maps JavaScript API، يُرجى الاطّلاع على الجدول أدناه للعثور على تفسيرات لرموز الخطأ.

رمز الخطأ رسالة الوصف
NotLoadingAPIFromGoogleMapsError يجب تنزيل Maps JavaScript API مباشرةً من خوادم Google.

لم يتم تضمين عنصر النص البرمجي الذي يحمّل واجهة برمجة تطبيقات JavaScript للخرائط بشكل صحيح في صفحتك. لكي تعمل واجهة برمجة التطبيقات بشكل صحيح، يجب تحميلها مباشرةً من https://maps.googleapis.com.

راجِع تحميل Maps JavaScript API.

TOSViolationMapError يبدو أنّ هذا الموقع الإلكتروني ينتهك بنود خدمة Google Maps API. تم إيقاف Google Maps API لهذا الموقع الإلكتروني.

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

إذا كان لديك ترخيص "خطة Premium" من "منصة خرائط Google"، يُرجى استخدام بيانات اعتماد "خطة Premium" من "منصة خرائط Google" لحلّ هذا الخطأ. راجِع دليل المصادقة في خطة Premium.

UnauthorizedURLForClientIdMapError عنوان URL هذا غير مصرَّح له باستخدام رقم تعريف عميل "خرائط Google" المقدَّم.

معرّف العميل الخاص بـ "الخطة المميزة" أو واجهات برمجة التطبيقات لخرائط Google للعمل المضمّن في عملية تحميل البرنامج النصي غير صالح أو منتهي الصلاحية، أو لم تتم إضافة العنوان الحالي الذي يتم تحميل واجهة برمجة تطبيقات JavaScript لخرائط Google منه إلى قائمة عناوين URL المسموح بها.

يُرجى الاطّلاع على تسجيل عناوين URL المسموح بها.

رموز الخطأ في Maps JavaScript API

إذا ظهر لك خطأ في وحدة تحكّم JavaScript في Chrome أو وحدة تحكّم الويب في Firefox أو أي أدوات أخرى مماثلة على متصفّحاتك، يُرجى الاطّلاع على الجدول أدناه للعثور على تفسيرات لرموز الخطأ.

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

رمز خطأ المطوّر النوع الوصف
ApiNotActivatedMapError خطأ

لم يتم تفعيل واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" في مشروع واجهة برمجة التطبيقات. قد تحتاج إلى تفعيل Maps JavaScript API ضمن واجهات برمجة التطبيقات في Google Cloud Console.

لتفعيل Maps JavaScript API لمشروعك، انقر على الزر أدناه.
كيفية إجراء ذلك

ApiTargetBlockedMapError خطأ

لا يُسمح لمفتاح واجهة برمجة التطبيقات هذا باستخدام هذه الخدمة أو واجهة برمجة التطبيقات. يُرجى التحقّق من إعدادات قيود واجهة برمجة التطبيقات لمفتاح واجهة برمجة التطبيقات في Google Cloud Console للتأكّد من أنّ جميع واجهات برمجة التطبيقات والخدمات التي تحتاج إلى استخدامها محدّدة بشكل صحيح في قائمة واجهات برمجة التطبيقات المفعَّلة.

يمكنك الاطّلاع على مفاتيح واجهة برمجة التطبيقات في وحدة تحكّم Cloud. لمزيد من المعلومات، راجِع أفضل الممارسات المتعلّقة بأمان واجهة برمجة التطبيقات.

DeletedApiProjectMapError خطأ

ربما تم حذف مشروع واجهة برمجة التطبيقات من Cloud Console. يُرجى التحقّق من المشروع الذي أنشأت له مفتاح واجهة برمجة التطبيقات المضمّن في أداة تحميل JavaScript API. يمكنك إنشاء مشروع جديد لواجهة برمجة التطبيقات والحصول على مفتاح جديد في Cloud Console.

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

ClientBillingNotEnabledMapError خطأ

لم يتم تفعيل الفوترة في مشروعك. يجب تفعيل الفوترة في مشروع Google Cloud المرتبط برقم تعريف العميل هذا، هنا.

BillingNotEnabledMapError خطأ

لم يتم تفعيل الفوترة في مشروعك، ما يؤدي إلى حدوث هذا الخطأ. يجب تفعيل الفوترة في مشروع Google Cloud هنا.

مزيد من المعلومات
ExpiredKeyMapError خطأ

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

للحصول على مفتاح واجهة برمجة التطبيقات، انقر على الزر أدناه.
البدء

InvalidAppCheckTokenMapError خطأ

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

راجِع دليل فحص التطبيقات.

InvalidClientIdMapError خطأ

لتعزيز أمان المصادقة وموثوقيتها، تم إيقاف معرّفات عملاء Maps Platform نهائيًا اعتبارًا من 26 مايو 2025، ولن يعود بالإمكان استخدامها بعد 31 مايو 2026. بدلاً من استخدام معرّف العميل، عليك استخدام بيانات اعتماد مفتاح واجهة برمجة التطبيقات للمصادقة على زيارات خدمة Google Maps API.

لمزيد من المعلومات، يُرجى الاطّلاع على دليل نقل أرقام تعريف العملاء. اتّبِع الخطوات الواردة في الدليل من أجل استعادة رقم تعريف العميل مؤقتًا.

InvalidKeyMapError خطأ

لم يتم العثور على مفتاح واجهة برمجة التطبيقات المُضمَّن في عنصر النص البرمجي الذي يتم تحميل واجهة برمجة التطبيقات منه. يُرجى التأكّد من استخدام مفتاح واجهة برمجة تطبيقات صحيح. يمكنك إنشاء مفتاح واجهة برمجة تطبيقات جديد في Cloud Console.

للحصول على مفتاح واجهة برمجة التطبيقات، انقر على الزر أدناه.
البدء

MalformedCredentialsMapError خطأ

يستخدم تطبيقك مخطّط URI غير متوافق. تأكَّد من أنّ التطبيق يستخدم تنسيق معرّف موارد منتظم (URI) صالحًا وفقًا لما هو محدّد في RFC 3986.

MissingKeyMapError خطأ

لا يتضمّن عنصر النص البرمجي الذي يحمّل واجهة برمجة التطبيقات مَعلمة المصادقة المطلوبة.

إذا كنت تستخدم واجهة برمجة التطبيقات Maps JavaScript API العادية، عليك استخدام المَعلمة key مع مفتاح صالح لواجهة برمجة التطبيقات. لمزيد من المعلومات، يُرجى الاطّلاع على بدء استخدام "منصة خرائط Google".

إذا كنت من عملاء "الخطة المميزة"، عليك استخدام المَعلمة client مع رقم تعريف العميل أو المَعلمة key مع مفتاح API صالح. لمزيد من المعلومات، راجِع دليل مفاتيح API وأرقام تعريف العملاء.

إذا لم تكن مالك الموقع الإلكتروني، لا يمكنك اتّخاذ أي خطوات لإصلاح هذا الخطأ، ولكن يمكنك إبلاغ مالك الموقع الإلكتروني إذا أمكن ذلك.
ProjectDeniedMapError خطأ

لم يتم إكمال طلبك. قد تتمكّن من العثور على مزيد من التفاصيل حول الخطأ في Cloud Console.

اطّلِع على Cloud Console.

RefererDeniedMapError خطأ

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

RefererNotAllowedMapError خطأ

لم تتم إضافة عنوان URL الحالي الذي يتم تحميل واجهة برمجة تطبيقات JavaScript لخرائط Google منه إلى قائمة المواقع المُحيلة المسموح بها. يُرجى التحقّق من إعدادات جهة الإحالة لمفتاح واجهة برمجة التطبيقات في Cloud Console.

يمكنك الاطّلاع على Maps JavaScript API والحصول على مفتاح واجهة برمجة التطبيقات.
OverQuotaMapError خطأ

تجاوز عدد الطلبات حدود الاستخدام المسموح بها في Maps JavaScript API. ستعمل طلبات تطبيقك مرة أخرى عند إعادة ضبط الحصة اليومية في المرة القادمة.

إذا لم تكن مالك الموقع الإلكتروني، لا يمكنك اتّخاذ أي خطوات لإصلاح هذا الخطأ، ولكن يمكنك إبلاغ مالك الموقع الإلكتروني إذا أمكن ذلك.

لمزيد من التفاصيل، يمكنك الاطّلاع على دليل حدود الاستخدام. توضّح الصفحة أيضًا كيفية الحصول على حدود استخدام أعلى.

ApiProjectMapError خطأ

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

لمزيد من المعلومات، يُرجى الاطّلاع على بدء استخدام "منصة خرائط Google".
ClientIdLooksLikeCryptoKey تحذير

من المحتمل أنّك قدّمت مفتاح تشفير في المَعلمة client. إذا كان لديك "خطة مميّزة" أو ترخيص Maps APIs for Work، يُرجى تحديد معرّف العميل كالمَعلمة client. لست بحاجة إلى استخدام مفتاح التشفير مع Maps JavaScript API.

يمكنك الاطّلاع على دليل معرّفات العملاء لمشتركي "الخطة المميزة" وعملاء واجهات برمجة التطبيقات في "خرائط Google للعمل".

ClientIdLooksLikeKey تحذير

ربما قدّمت مفتاح واجهة برمجة تطبيقات في المَعلمة client. إذا كان لديك "خطة Premium" أو ترخيص Maps APIs for Work، يُرجى تحديد معرّف العميل كالمَعلمة client. إذا كان لديك "خطة Premium" من "منصة خرائط Google"، يمكنك استخدام المَعلمة client أو المَعلمة key. إذا لم يكن لديك أي تراخيص، عليك استخدام المَعلمة key بدلاً من المَعلمة client .

راجِع دليل المصادقة في خطة Premium.

InvalidChannel تحذير

ربما قدّمت مَعلمة channel غير صالحة. يجب أن تكون القناة سلسلة أبجدية رقمية بتنسيق ASCII، ويمكن أن تتضمّن نقطة (.) وشرطة سفلية (_) وواصلة (-). يُرجى التأكّد من تحديد مَعلمة channel صالحة.

اطّلِع على إعداد التقارير | خطة Premium في "منصة خرائط Google".

InvalidClientId تحذير

يبدو أنّ المَعلمة client لا تحتوي على معرّف عميل صحيح. يجب أن يبدأ معرّف العميل بـ "gme-".

راجِع دليل المصادقة في خطة Premium.

InvalidKey تحذير

يبدو أنّ مفتاح واجهة برمجة التطبيقات المُضمَّن في عنصر النص البرمجي الذي يحمّل واجهة برمجة التطبيقات غير صحيح. يُرجى التأكّد من استخدام مفتاح واجهة برمجة تطبيقات صحيح. يمكنك إنشاء مفتاح واجهة برمجة تطبيقات جديد في Cloud Console.

للحصول على مفتاح واجهة برمجة التطبيقات، انقر على الزر أدناه.
البدء

InvalidVersion تحذير

ربما قدّمت رقم إصدار غير صحيح في عنصر النص البرمجي. يُرجى التأكّد من استخدام رقم إصدار صحيح.

يُرجى الاطّلاع على إصدارات واجهة برمجة التطبيقات | Google Maps JavaScript API.

KeyLooksLikeClientId تحذير ربما قدّمت معرّف عميل كمَعلمة key. إذا كان لديك "خطة مميّزة" أو ترخيص واجهات برمجة تطبيقات "خرائط Google" للعمل، يُرجى تحديد معرّف العميل كمعلَمة client بدلاً من المَعلمة key. إذا كان لديك "خطة Premium" من "منصة خرائط Google"، يمكنك استخدام المَعلمة client أو المَعلمة key. إذا لم يكن لديك أي تراخيص، عليك استخدام المَعلمة key بدلاً من المَعلمة client .

راجِع دليل المصادقة في خطة Premium.

KeyLooksLikeCryptoKey تحذير

ربما قدّمت مفتاح تشفير أو سر توقيع كمعلَمة key. إذا كان لديك "خطة مميّزة" أو ترخيص لاستخدام واجهات برمجة التطبيقات في "خرائط Google للعمل"، يُرجى تحديد معرّف العميل كمعلَمة client وإزالة المَعلمة key من عنصر النص البرمجي. لا يلزم استخدام مفتاح التشفير لواجهة برمجة التطبيقات JavaScript لـ "خرائط Google". إذا كان لديك "خطة Premium" من "منصة خرائط Google"، يمكنك استخدام المَعلمة client أو المَعلمة key. إذا لم يكن لديك أي تراخيص، يمكنك الحصول على مفتاح API في Cloud Console.

راجِع الدليل حول تحديد معرّف العميل عند تحميل واجهة برمجة التطبيقات.

KeyLooksLikeProjectNumber تحذير

ربما قدّمت رقم مشروع كمعلَمة key. يُرجى التأكّد من استخدام مفتاح واجهة برمجة تطبيقات صحيح. يمكنك إنشاء مفتاح واجهة برمجة تطبيقات جديد في Cloud Console.

كيفية الحصول على مفتاح واجهة برمجة التطبيقات
NoApiKeys تحذير

لا يحتوي عنصر النص البرمجي الذي يحمّل واجهة برمجة التطبيقات على مفتاح واجهة برمجة تطبيقات. يُرجى التأكّد من تضمين مفتاح صالح لواجهة برمجة التطبيقات كمعلَمة key. يمكنك إنشاء مفتاح واجهة برمجة تطبيقات جديد في Cloud Console.

للحصول على مفتاح واجهة برمجة التطبيقات، انقر على الزر أدناه للبدء.
البدء

إذا كنت تحمّل واجهة برمجة تطبيقات JavaScript لخرائط Google من المسار المتوقّف نهائيًا v2، سيظهر لك التحذير NoApiKeys، حتى إذا حدّدت المَعلمة key. يُرجى الاطّلاع على دليل الترقية من الإصدار 2 إلى الإصدار 3 ونقل تطبيقك إلى الإصدار 3 من واجهة برمجة تطبيقات JavaScript لخرائط Google.

RetiredVersion تحذير

ربما قدّمت إصدارًا قديمًا في عنصر النص البرمجي. يُرجى تحديث التطبيق لاستخدام أحد الإصدارات المتاحة.

يُرجى الاطّلاع على إصدارات واجهة برمجة التطبيقات | Google Maps JavaScript API.

SensorNotRequired تحذير

لم تعُد المَعلمة sensor مطلوبة في Maps JavaScript API. لن يؤدي ذلك إلى منع واجهة برمجة تطبيقات JavaScript لخرائط Google من العمل بشكل صحيح، ولكن ننصحك بإزالة المَعلمة sensor من عنصر النص البرمجي.

SignatureNotRequired تحذير

لا يلزم استخدام المَعلمة signature مع Maps JavaScript API. لن يمنع ذلك واجهة برمجة تطبيقات JavaScript لخرائط Google من العمل بشكل صحيح، ولكن قد يؤدي إلى حدوث مخاطر أمنية. يُرجى إزالته من عنصر النص البرمجي.

SignedInNotSupported تحذير

تم إيقاف المعلَمة signed_in نهائيًا، وهي غير متاحة في إصدار Maps JavaScript API الذي تستخدمه. لن يؤدي ذلك إلى منع عمل واجهة برمجة تطبيقات JavaScript لـ "خرائط Google"، ولكن قد يتغير سلوك تطبيقك إذا كنت تعتمد على الميزات التي تتطلّب تسجيل الدخول.

UrlAuthenticationCommonError خطأ

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

التحقّق من الأخطاء في المتصفّح

تكتب Maps JavaScript API رسائل الخطأ إلى window.console. يوضّح هذا القسم كيفية التحقّق من ناتج window.console في Google Chrome. إذا كنت تستخدم أي متصفحات أخرى، يُرجى الرجوع إلى مستندات المطوّرين الخاصة بالمتصفح. للعلم، إليك قائمة بالأدوات التي يمكنك استخدامها للتحقّق من ناتج window.console في بعض المتصفّحات الأخرى.

في Chrome، يمكنك استخدام وحدة تحكّم JavaScript للتحقّق من ناتج window.console على النحو التالي.

  1. لفتح "أدوات المطوّرين"، انقر على رمز القائمة > المزيد من الأدوات > أدوات المطوّرين.
  2. لفتح "وحدة تحكّم JavaScript"، اضغط على مفتاح ESC على لوحة المفاتيح. سيؤدي الضغط على مفتاح ESC إلى تبديل "وحدة تحكّم JavaScript". إذا أغلقت وحدة التحكّم، اضغط على مفتاح ESC مرة أخرى لفتحها.

في حال حدوث أي أخطاء أو تحذيرات عند تحميل Maps JavaScript API، ستظهر كسطر واحد أو أكثر في وحدة التحكّم. يكون تنسيق رسالة الخطأ أو التحذير على النحو التالي:

‫Google Maps API error: [ERROR CODE] [Link to API document]
أو
Google Maps API warning: [ERROR CODE] [Link to API document]

يمكنك الاطّلاع على جدول رموز الخطأ أعلاه للعثور على رمز الخطأ في رسالة الخطأ. يمكنك أيضًا العثور على تفاصيل حول رسالة الخطأ في مستند واجهة برمجة التطبيقات المرتبط من الرسالة.

ملاحظة: يمكنك الاستماع إلى أخطاء المصادقة آليًا.

التعامل مع المتصفّحات غير المتوافقة

تأكَّد من أنّ إصدار المتصفّح الذي تستخدمه متوافق حاليًا مع واجهة برمجة تطبيقات JavaScript لـ "خرائط Google".

إذا كنت بصدد تطوير تطبيق أصلي لنظام التشغيل Windows يعمل في WebView، تأكَّد من أنّك تستخدم WebView2 المستند إلى Edge. لم تعُد الإصدارات السابقة من WebView، المستندة إلى Internet Explorer، متاحة.

في حال استمرار تعطُّل الرمز

لمساعدتك في إعداد رمز الخرائط وتشغيله، يوضّح كل من "بريندان كيني" و"مانو ماركس" بعض الأخطاء الشائعة وكيفية حلّها في هذا الفيديو.

  • ابحث عن الأخطاء الإملائية، وتذكَّر أنّ JavaScript هي لغة حساسة لحالة الأحرف.
  • تحقَّق من الأساسيات، فبعض المشاكل الأكثر شيوعًا تحدث عند إنشاء الخريطة في البداية، مثل:
    • تأكَّد من أنّك حدّدت السمتَين zoom وcenter في خيارات الخريطة.
    • تأكَّد من أنّك حدّدت عنصر div سيتم عرض الخريطة فيه على الشاشة.
    • تأكَّد من أنّ عنصر div الخاص بالخريطة يتضمّن ارتفاعًا. يتم تلقائيًا إنشاء عناصر div بارتفاع 0، وبالتالي تكون غير مرئية.
    يمكنك الرجوع إلى الأمثلة التي نقدّمها للحصول على مرجع لعملية التنفيذ.
  • استخدِم برنامج تصحيح JavaScript للمساعدة في تحديد المشاكل، مثل الأداة المتوفّرة في أدوات مطوّري برامج Chrome. ابدأ بالبحث عن الأخطاء في وحدة تحكّم JavaScript.
  • طرح الأسئلة على Stack Overflow تتوفّر إرشادات حول كيفية نشر أسئلة رائعة على صفحة الدعم.