رسائل الخطأ في واجهة برمجة التطبيقات الثابتة للخرائط
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
قد تُصدر واجهة برمجة التطبيقات الثابتة للخرائط خطأً أو تحذيرًا عندما يحدث شيء ما
خطأ. يوضّح هذا الدليل كل رسالة خطأ، ويقدّم المزيد من الخطوات المتعلّقة بحلّ الأخطاء.
الطلبات غير الصالحة
في حالة وجود طلب غير صالح، تعرض واجهة برمجة التطبيقات الثابتة للخرائط
رمز حالة HTTP 4xx ورسالة تصف
المشكلة. في ما يلي أمثلة على حالات الخطأ هذه. ملاحظة: هذه ليست
قائمة شاملة بالأخطاء المحتمَلة. يُرجى التحقق من رمز الخطأ الفعلي.
والرسالة التي تعرضها واجهة برمجة التطبيقات للحصول على تفاصيل حول مشاكل محددة.
مثال على حالة الخطأ
رمز الحالة
يتضمن الطلب معلَمة غير صالحة، أو تتضمن المعلمة المطلوبة
مفقودة. على سبيل المثال، لا تقع المَعلمة size ضمن
النطاق المتوقّع للقيم الرقمية، أو تكون غير متوفّرة في الطلب.
400 BAD REQUEST
مفتاح واجهة برمجة التطبيقات المضمّن في الطلب غير صالح.
403 FORBIDDEN
الأخطاء التي تمنع عرض الخريطة
إذا كان الطلب صالحًا، ولكن حدث خطأ آخر يمنع عرض
الخريطة، ستعرض واجهة برمجة التطبيقات Maps Static API إما نصًا أو
صورة خطأ بدلاً من الخريطة، وذلك استنادًا إلى الخطأ. مثال على هذا الخطأ
هو عندما يتجاوز التطبيق
حدود الاستخدام.
الشكل: صورة خطأ يتمّ عرضها بدلاً من خريطة
الأخطاء المتعلقة بمفاتيح واجهة برمجة التطبيقات والفوترة
في حال استخدام واجهة برمجة التطبيقات Maps Static API بدون مفتاح واجهة برمجة التطبيقات، أو في حال كانت الفوترة
لم يتم تفعليها في حسابك، فستعرض الصفحة صورة خطأ بدلاً من
مع رابط يشير إلى نوع الخطأ. على سبيل المثال:
"g.co/staticmaperror/key".
الأخطاء والحلول بدون مفاتيح
أنت تستخدم واجهة برمجة التطبيقات الثابتة للخرائط بدون مفتاح واجهة برمجة التطبيقات. لحلّ هذه المشكلة، عليك:
لا يتضمّن طلبك توقيعًا رقميًا (مطلوب). لحل المشكلة،
توقيع عنوان URL
تتضمّن تحذيرات
بالنسبة إلى بعض حالات الخطأ، تعرض واجهة برمجة التطبيقات خريطة ولكن قد يتم عرض بعض المعلومات
مفقود من الخريطة. عندما يحدث هذا، يحدث شرطان لإخبارك
التحذير.
أولاً، يتم عرض الخريطة، ولكن مع وجود شريط خطأ أصفر متراكب فوق
في أعلى الخريطة مع النص "خطأ في الخريطة: g.co/staticmaperror".
ثانيًا، تعرض واجهة برمجة التطبيقات تحذيرًا في
شكل عنوان HTTP باسم X-Staticmap-API-Warning.
على سبيل المثال، يحتوي عنوان URL التالي على قيمة غير متوقّعة في المَعلمة
markers:
حدث خطأ أثناء محاولة ترميز الطلب جغرافيًا. هناك
العديد من الصيغ لهذه الرسالة، استنادًا إلى العنصر الذي تعذّر فيه تحديد الموقع الجغرافي
(المركز أو العلامة أو العنصر المرئي أو المسار) وعدد العناصر
التي تعذّر فيها تحديد الموقع الجغرافي. أحد الأمثلة على هذا التحذير
X-Staticmap-API-Warning:Error geocoding: marker 1، باسم
كما هو موضح في المثال أعلاه.
Too many geocoded markers requested (max is 15).
يحدِّد الطلب أكثر من الحد الأقصى المسموح به لعدد العلامات
التي لها عنوان يمكن لشخص عادي قراءته. الحد الأقصى هو 15. تجدر الإشارة إلى أنّ هذا الحدّ الأقصى
لا ينطبق إلا على العلامات المحدّدة كعنوان يمكن لشخص عادي قراءته ويتطلب
ترميزًا جغرافيًا. ولا ينطبق على العلامات المحددة باستخدام
إحداثيات خطوط العرض/خطوط الطول.
Too many geocoded polyline vertices requested (max is 15).
يحدِّد الطلب أكثر من الحد الأقصى المسموح به لعدد الخطوط المتعددة
التي تتضمّن عنوانًا يمكن لشخص عادي قراءته. الحد الأقصى هو 15. يُرجى العِلم أنّ هذا الحدّ القصوى
لا ينطبق إلا على الخطوط المتعددة الأشكال التي تحتوي على رؤوس محدّدة كعناوين قابلة للقراءة من قِبل البشر والتي
تتطلّب ترميزًا جغرافيًا. ولا ينطبق ذلك على الخطوط المتعددة المحدّدة باستخدام
إحداثيات خطوط الطول/العرض.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Maps Static API returns errors as HTTP status codes or warning messages for invalid requests, usage limits, or issues with API keys and billing.\u003c/p\u003e\n"],["\u003cp\u003eErrors that prevent map display can result in error images or text messages instead of the map, with details provided in the response.\u003c/p\u003e\n"],["\u003cp\u003eWarnings about potential issues, like geocoding problems or marker limits, are indicated by a yellow error bar on the map and HTTP header warnings.\u003c/p\u003e\n"],["\u003cp\u003eFor invalid requests, refer to the HTTP status code (e.g., 400, 403) and message for details about the specific issue.\u003c/p\u003e\n"],["\u003cp\u003eAlways check for HTTP header warnings and the yellow error bar to ensure your map is displayed correctly and address potential issues.\u003c/p\u003e\n"]]],[],null,["# Error Messages in Maps Static API\n\nThe Maps Static API may issue an error or warning when something goes\nwrong. This guide explains each error message, and provides further\ninstructions for resolving errors.\n\nInvalid requests\n----------------\n\nIn the case of an invalid request, the Maps Static API returns\nan HTTP `4xx` status code and a message describing the\nproblem. Below are examples of such error conditions. Note: This is not\na complete list of the possible errors. Please 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 `size` parameter is not within the expected range of numeric values, or is missing from the request. | `400 BAD REQUEST` |\n| The API key included in the request is invalid. | `403 FORBIDDEN` |\n\nErrors that prevent a map from being displayed\n----------------------------------------------\n\nIf the request is valid, but another error occurs that prevents the map from\nbeing displayed, the Maps Static API returns either text or an error\nimage instead of the map, depending on the error. An example of such an error\ncondition is when the application exceeds its\n[usage limits](/maps/documentation/maps-static/usage-limits).\n\nFigure: An error image displayed instead of a map\n\n### Errors related to API keys and billing\n\nIf you use the Maps Static API without an API key, or if billing\nis not enabled on your account, the page displays an error image instead of a\nmap, with a link indicating the type of error. For example\n\"g.co/staticmaperror/key\".\n\n| Keyless errors and solutions ||\n|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| | You are using the Maps Static API without an API key. To resolve, you must: 1. [Get an API key](/maps/documentation/maps-static/get-api-key#get-an-api-key) 2. [Enable billing](https://console.cloud.google.com/project/_/billing/enable?utm_source=Docs_BillingNudge) 3. [Sign your URL](/maps/documentation/maps-static/get-api-key#digital-signature) |\n| | Your request is missing a digital signature (required). To resolve, [Sign your URL](/maps/documentation/maps-static/get-api-key#digital-signature) |\n\nWarnings\n--------\n\nFor some error conditions, the API returns a map but some information may\nbe missing from the map. When this happens, two conditions occur to inform you of\nthe warning.\n\n- One, the map displays, but with a yellow error bar superimposed over top of the map with the text \"Map error: g.co/staticmaperror\".\n- Two, the API returns a warning in the form of an HTTP header named `X-Staticmap-API-Warning`.\n\nFor example, the following URL contains an unexpected value in the\n`markers` parameter: \n\n```\nhttps://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY\n```\n\nThe API returns a map, but displays a yellow error bar superimposed\nover the image with \"Map error: g.co/staticmaperror\":\n\nThe API also returns the following HTTP header: \n\n```\nX-Staticmap-API-Warning:Error geocoding: marker 1\n```\n\nThe following table describes the warnings that the API may issue as HTTP\nheaders:\n\n| Warnings in `X-Staticmap-API-Warning` headers ||\n|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]*` | An error occurred while attempting to geocode the request. There are many variants of this message, depending on the element where geocoding failed (center, marker, visible, or path) and the number of elements that failed. One example of this warning is `X-Staticmap-API-Warning:Error geocoding: marker 1`, as shown in the above example. |\n| `Too many geocoded markers requested (max is 15).` | The request specifies more than the allowed maximum number of markers with a human readable address. The maximum is 15. Note that this limit applies only to markers specified as a human-readable address that requires geocoding. It does not apply to markers specified with latitude/longitude coordinates. |\n| `Too many geocoded polyline vertices requested (max is 15).` | The request specifies more than the allowed maximum number of polylines with a human readable address. The maximum is 15. Note that this limit applies only to polylines with vertices specified as human-readable addresses that require geocoding. It does not apply to polylines specified with latitude/longitude coordinates. |\n\nYou can see the HTTP header warnings in the\n[Chrome DevTools Console](/web/tools/chrome-devtools/console/console-write#errors_and_warnings), the\n[Firefox\nWeb Console](https://developer.mozilla.org/en-US/docs/Tools/Web_Console), or other equivalent tools in your browser.\n| **Note:** You should check for HTTP header warnings if you notice the yellow error bar on the map indicating that something may be missing from the map. It's also a good idea to check for warnings before launching a new application. Consider also whether user input or internationalization could lead to unexpected characters or malformed latitude/longitude coordinate specifications in the request."]]
