رسائل الخطأ
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
توضّح هذه الصفحة رسائل الخطأ التي يمكن أن تعرِضها واجهة برمجة التطبيقات
Maps Embed API. عند حدوث خطأ، تعرِض واجهة برمجة التطبيقات
Maps Embed API نص رسالة الخطأ بدلاً من الخريطة.
قد تحدث أيضًا حالات خطأ معيّنة تؤدي إلى عرض
خريطة مظلّلة عليها علامة مائية.
الطلبات غير الصالحة
في حال تقديم طلب غير صالح، تعرض واجهة برمجة التطبيقات Maps Embed API
رمز حالة HTTP 4xx ورسالة توضّح
المشكلة. في ما يلي أمثلة على حالات الخطأ. ملاحظة: هذه ليست
قائمة شاملة بالأخطاء المحتمَلة. تحقّق من رمز الخطأ
والرسالة الفعلية التي تعرضها واجهة برمجة التطبيقات للحصول على تفاصيل عن مشاكل معيّنة.
| مثال على حالة الخطأ |
رمز الحالة |
يتضمّن الطلب مَعلمة غير صالحة، أو هناك مَعلمة مطلوبة مفقودة. على سبيل المثال، لا تقع المَعلمة zoom ضمن
النطاق المتوقّع للقيم الرقمية، أو لا تتوفّر مَعلمة مطلوبة في
الطلب. |
400 BAD REQUEST |
| مفتاح واجهة برمجة التطبيقات المضمّن في الطلب غير صالح. |
403 FORBIDDEN |
أخطاء مفتاح واجهة برمجة التطبيقات والحصة
يتم التعامل مع أخطاء مفتاح واجهة برمجة التطبيقات والحصة كطلبات غير صالحة. تشمل الأسباب المحتملة
ما يلي:
أخطاء الفوترة ومُحيل HTTP
يتم عرض خريطة مظلمة أو صورة "سلبية" من "التجوّل الافتراضي"، عليها علامة مائية "لأغراض تطوير فقط"، عندما يكون أيّ مما يلي صحيحًا:
التحقّق من الأخطاء في المتصفّح
بالنسبة إلى أخطاء "الفوترة" وHTTP المُحيل، تُسجِّل واجهة برمجة التطبيقات Maps Embed API
رسائل الخطأ في window.console. بالنسبة إلى الطلبات غير الصالحة (بما في ذلك
أخطاء مفتاح واجهة برمجة التطبيقات والحصة)، يتم تسجيل رمز حالة HTTP 4xx فقط
في وحدة التحكّم. يوضّح هذا القسم كيفية التحقّق من إخراج وحدة التحكّم في Chrome. إذا كنت تستخدم أي متصفّحات أخرى، يُرجى الاطّلاع على مستندات المطوّرين الخاصة بالمتصفّح. في ما يلي قائمة بالأدوات التي يمكنك استخدامها للتحقّق من مخرجات وحدة التحكّم في بعض المتصفّحات الأخرى.
في Chrome، يمكنك استخدام
وحدة تحكّم JavaScript
للتحقّق من إخراج وحدة التحكّم على النحو التالي.
-
لفتح "أدوات المطوّرين"، انقر على رمز القائمة > المزيد من الأدوات >
أدوات المطوّرين.
-
لفتح وحدة تحكّم JavaScript، انقر على علامة التبويب Console في أعلى
نافذة "أدوات المطوّرين". يمكنك أيضًا استخدام مفتاح ESC لتفعيل
وحدة تحكّم JavaScript وإيقافها.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Maps Embed API displays error messages in place of the map or as a darkened, watermarked map when errors occur.\u003c/p\u003e\n"],["\u003cp\u003eInvalid requests result in a \u003ccode\u003e4xx\u003c/code\u003e HTTP status code and a descriptive error message, often due to missing or incorrect parameters or an invalid API key.\u003c/p\u003e\n"],["\u003cp\u003eAPI key and quota errors are treated as invalid requests, and can stem from a missing, invalid, or restricted API key, or a disabled API.\u003c/p\u003e\n"],["\u003cp\u003eBilling and HTTP referer errors result in a darkened, watermarked map, and may be caused by billing issues, exceeding usage limits, or missing HTTP referers.\u003c/p\u003e\n"],["\u003cp\u003eError messages for billing and referer issues can be found in the browser's console; invalid request errors show only the HTTP status code.\u003c/p\u003e\n"]]],["The Maps Embed API displays error messages or a watermarked map when issues occur. Invalid requests trigger a `4xx` status code, indicating problems like missing or incorrect parameters or an invalid API key. Billing or HTTP referer issues result in a watermarked map, caused by disabled billing, invalid payment, exceeded limits, or missing referers. Errors are logged in the browser's console (`window.console`) and can be checked via browser developer tools.\n"],null,["This page describes the error messages that can be returned by the\nMaps Embed API. When an error occurs, the\nMaps Embed API presents error message text in place of the map.\nCertain error conditions may also occur, which result in the display of a\ndarkened watermarked map.\n\nInvalid requests\n\nIn the case of an invalid request, the Maps Embed API returns\nan HTTP `4xx` status code and a message describing the\nproblem. Below are examples of error conditions. Note: This is not\na complete list of the possible errors. Check the actual error code\nand message returned by the API for details of specific problems.\n\n| Example of error condition | Status code |\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|\n| The request includes an invalid parameter, or a required parameter is missing. For example, the `zoom` parameter is not within the expected range of numeric values, or a required parameter is missing from the request. | `400 BAD REQUEST` |\n| The API key included in the request is invalid. | `403 FORBIDDEN` |\n\nAPI key and quota errors\n\nAPI key and quota errors are treated as invalid requests. Possible causes\ninclude the following:\n\n- Missing or invalid API key. To resolve this error, ensure that your request includes a valid API key. [Get an API key](/maps/documentation/embed/get-api-key#get-an-api-key).\n- Maps Embed API is not enabled for your project. Learn about [enabling and disabling APIs](https://cloud.google.com/apis/docs/enable-disable-apis).\n- API key has a restriction violation. [Read\n more about API key best practices](/maps/api-key-best-practices).\n\nBilling and HTTP referer errors\n\nA darkened map, or \"negative\" Street View image, watermarked with \"for\ndevelopment purposes only\" is returned when any of the following is true:\n\n- Billing has not been enabled on your account. [Enable billing](https://console.cloud.google.com/project/_/billing/enable?utm_source=Docs_BillingNudge).\n- The provided billing method is invalid (for example an expired credit card). To resolve this, visit the [Google Cloud console, and ensure that you have provided a valid method of payment.](https://console.cloud.google.com/project/_/billing)\n- A self-imposed daily limit has been exceeded. [Learn how to view or change daily billable limits](/maps/documentation/embed/usage-and-billing#set-caps).\n- The request is missing an HTTP referer, and you are using a referer-restricted API key. [Learn\n more about adding referers](/maps/api-key-best-practices).\n\nCheck errors in your browser\n\nFor Billing and HTTP referer errors, the Maps Embed API writes\nerror messages to `window.console`. For invalid requests (including\nAPI key and quota errors), only the HTTP `4xx` status code is reported\nin the console. This section explains how you can check the console output in\nGoogle Chrome. If you are using any other browsers, please check the developer\ndocumentation for your browser. For your reference, this is a list of tools to\ncheck console output in some other browsers.\n\n- [Console](https://msdn.microsoft.com/en-us/library/dn255006(v=vs.85).aspx) for Internet Explorer.\n- [Web Console](https://developer.mozilla.org/en-US/docs/Tools/Web_Console) for Firefox.\n- [Remote debugging](https://developer.chrome.com/devtools/docs/remote-debugging) for Android.\n- [Web Inspector](https://developer.apple.com/library/safari/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/GettingStarted/GettingStarted.html) for iOS.\n\n\nIn Chrome, you can use the\n[JavaScript Console](/web/tools/chrome-devtools/debug/console)\nto check console output as follows.\n\n1. To open the Developer Tools, select the menu icon \\\u003e **More Tools** \\\u003e **Developer Tools**.\n2. To open the JavaScript Console, click the **Console** tab at the top of the Developer Tools window. You can also use the ESC key to toggle the JavaScript Console."]]
