הודעות שגיאה

בדף הזה מתוארות הודעות השגיאה שיכולות להתקבל מ-Maps JavaScript API. ‫Maps JavaScript API כותב הודעות שגיאה ואזהרה בלוח JavaScript. יכול להיות שיופיעו גם שגיאות מסוימות, שיגרמו להצגת מפה כהה עם סימן מים.

שגיאות במפתח ה-API ובחיוב

פתרון בעיות

בנסיבות מסוימות, יכול להיות שתוצג מפה כהה או תמונת Street View "שלילית" עם סימן מים שכולל את הטקסט "למטרות פיתוח בלבד". ההתנהגות הזו בדרך כלל מצביעה על בעיות במפתח ה-API או בחיוב. כדי להשתמש במוצרים של Google Maps Platform, צריך להפעיל את החיוב בחשבון וכל הבקשות צריכות לכלול מפתח API תקין. כדי לקבל עזרה במציאת הודעות שגיאה, עיינו בקטע בדיקת שגיאות בדפדפן.

התהליך הבא יעזור לכם לפתור את הבעיה.

קודי שגיאה של Maps JavaScript API למפתחים ולבעלי אתרים

בטבלאות הבאות מפורטים קודי השגיאה האפשריים שמוחזרים על ידי Maps JavaScript API, עם תיאור של הסיבה ואיך אפשר לפתור את הבעיה. כדי למצוא את הודעות השגיאה, אפשר להיעזר בקטע בדיקת שגיאות בדפדפן.

שגיאות בטעינת המפה

אם נתקלתם בשגיאה בזמן הטעינה של Maps JavaScript API, תוכלו להיעזר בטבלה הבאה כדי למצוא הסברים על קודי השגיאה.

קוד השגיאה שליחת הודעה תיאור
NotLoadingAPIFromGoogleMapsError צריך להוריד את Maps JavaScript API ישירות מהשרתים של Google.

רכיב הסקריפט שטוען את Maps JavaScript API לא נכלל בדף בצורה נכונה. כדי שה-API יפעל כמו שצריך, צריך לטעון אותו ישירות מ-https://maps.googleapis.com.

טעינת Maps JavaScript API

TOSViolationMapError נראה שהאתר הזה מפר את התנאים וההגבלות של Google Maps API. ‫Google Maps API הושבת באתר הזה.

האפליקציה שלך נחסמה בגלל אי-עמידה בתנאים ובהגבלות של Google Maps Platform, אחרי שנשלחו כמה התראות באימייל. כדי לערער על החסימה ולבקש בדיקה של ההטמעה, צריך למלא את טופס הערעור על התנאים וההגבלות של הפלטפורמה של מפות Google. תשובה תישלח אליך באימייל תוך כמה ימי עסקים.

כדי לפתור את השגיאה הזו, צריך להשתמש במפתח ה-API או בפרטי הכניסה של מזהה הלקוח. מדריך למפתחות API ולמזהי לקוחות

UnauthorizedURLForClientIdMapError לכתובת ה-URL הזו אין הרשאה להשתמש במזהה הלקוח שצוין במפות Google.

מזהה הלקוח שכלול בטעינת הסקריפט לא תקין, פג תוקף או שהכתובת הנוכחית שטוענת את Maps JavaScript API לא נוספה לרשימת כתובות ה-URL המורשות.

רישום כתובות URL מורשות

קודי שגיאה ב-Maps JavaScript API

אם מופיעה שגיאה במסוף JavaScript ב-Chrome, במסוף האינטרנט ב-Firefox או בכל כלי מקביל אחר בדפדפנים, אפשר לעיין בטבלה הבאה כדי למצוא הסברים לקודי השגיאה.

‫Maps JavaScript API מחזיר גם שגיאות וגם אזהרות. שגיאה מצביעה על בעיה חמורה שהתרחשה במהלך הטעינה של Maps JavaScript API. הדף לא יכול לטעון את ה-API כמו שצריך, וה-API לא יפעל בדף הזה. אזהרה היא הודעה משלימה לגבי הטעינה של Maps JavaScript API. האזהרה מתארת את הסיבות האפשריות לשגיאה, או מצביעה על בעיות פוטנציאליות בקוד שטוען את Maps JavaScript API. אם אתם מקבלים רק אזהרות בלי שגיאות, ה-API יפעל כמו שצריך בדף הזה. עם זאת, מומלץ לתקן גם את הבעיות הפוטנציאליות האלה.

קוד שגיאה למפתחים סוג תיאור
ApiNotActivatedMapError שגיאה

‫Maps JavaScript API לא מופעל בפרויקט ה-API שלכם. יכול להיות שתצטרכו להפעיל את Maps JavaScript API בקטע APIs במסוף Google Cloud.

כדי להפעיל את Maps JavaScript API בפרויקט, לוחצים על הכפתור שלמטה.
איך עושים את זה

ApiTargetBlockedMapError שגיאה

מפתח ה-API הזה לא מורשה להשתמש בשירות או ב-API הזה. כדי לוודא שכל ממשקי ה-API והשירותים שאתם צריכים להשתמש בהם מופיעים בצורה נכונה ברשימת ממשקי ה-API המופעלים, בדקו את ההגדרות של הגבלות ה-API של מפתח ה-API במסוף Google Cloud.

מפתחות API במסוף Cloud מידע נוסף זמין במאמר שיטות מומלצות לאבטחת API.

DeletedApiProjectMapError שגיאה

יכול להיות שפרויקט ה-API נמחק ממסוף Cloud. צריך לבדוק את הפרויקט שבו נוצר מפתח ה-API שכלול ב-JavaScript API loader. אפשר ליצור פרויקט API חדש ולקבל מפתח חדש במסוף Cloud.

כדי ליצור פרויקט חדש ולקבל מפתח API לפרויקט, לוחצים על הכפתור שלמטה.
איך עושים את זה

ClientBillingNotEnabledMapError שגיאה

לא הפעלתם את החיוב בפרויקט. צריך להפעיל את החיוב בפרויקט ב-Google Cloud שמשויך למזהה הלקוח הזה.

BillingNotEnabledMapError שגיאה

השגיאה הזו נגרמת כי לא הפעלתם את החיוב בפרויקט. צריך להפעיל את החיוב בפרויקט ב-Google Cloud.

מידע נוסף
ExpiredKeyMapError שגיאה

מפתח ה-API שכלול ברכיב הסקריפט שטוען את ה-API פג תוקף או לא מזוהה על ידי המערכת. יכול להיות שתקבלו את השגיאה הזו אחרי שתיצרו מפתח API חדש, אם תנסו להשתמש במפתח לפני שהמערכת תזהה אותו. צריך לחכות כמה דקות ולנסות שוב, או ליצור מפתח API חדש במסוף Cloud.

כדי לקבל מפתח API, לוחצים על הכפתור שלמטה.
קדימה, מתחילים

InvalidAppCheckTokenMapError שגיאה

האסימון של App Check שסופק לא תקין או שהתוקף שלו פג. השגיאה הזו יכולה להתרחש רק אם נעשה שימוש באימות של App Check.

מדריך לאימות באמצעות App Check

InvalidClientIdMapError שגיאה

כדי לשפר את האבטחה והאמינות של האימות, מזהי הלקוח של הפלטפורמה של מפות Google הוצאו משימוש ב-26 במאי 2025, ולא ניתן יהיה להשתמש בהם אחרי 31 במאי 2026. במקום להשתמש במזהה לקוח, צריך להשתמש בפרטי כניסה של מפתח API כדי לאמת את תנועת הנתונים בשירות Google Maps API.

מידע נוסף זמין במדריך להעברת נתונים (מיגרציה) של מזהה לקוח. פועלים לפי השלבים במדריך כדי לשחזר את מזהה הלקוח באופן זמני.

InvalidKeyMapError שגיאה

מפתח ה-API שכלול ברכיב הסקריפט שטוען את ה-API לא נמצא. חשוב לוודא שאתם משתמשים במפתח API תקין. אפשר ליצור מפתח API חדש במסוף Cloud.

כדי לקבל מפתח API, לוחצים על הכפתור שלמטה.
קדימה, מתחילים

MalformedCredentialsMapError שגיאה

האפליקציה משתמשת בסכמת URI לא נתמכת. מוודאים שהאפליקציה משתמשת בפורמט URI תקין, כמו שמוגדר ב-RFC 3986.

MissingKeyMapError שגיאה

באלמנט הסקריפט שטוען את ה-API חסר פרמטר האימות הנדרש.

אם אתם משתמשים ב-Maps JavaScript API, אתם צריכים להשתמש בפרמטר key עם מפתח API תקין. מידע נוסף זמין במאמר תחילת העבודה עם Google Maps Platform.

אם משתמשים במזהה לקוח, צריך להשתמש בפרמטר client עם מזהה הלקוח, או בפרמטר key עם מפתח API חוקי. מידע נוסף זמין במדריך בנושא מפתחות API ומזהי לקוחות.

אם אתם לא בעלי האתר, אין לכם אפשרות לתקן את השגיאה הזו. עם זאת, כדאי להודיע לבעלי האתר אם אפשר.
ProjectDeniedMapError שגיאה

הבקשה שלך לא הושלמה. יכול להיות שתוכלו למצוא פרטים נוספים על השגיאה במסוף Cloud.

למסוף Cloud

RefererDeniedMapError שגיאה

האפליקציה שלך נחסמה בגלל אי-עמידה בתנאים ובהגבלות של Google Maps Platform, אחרי שנשלחו כמה התראות באימייל. כדי לערער על החסימה ולבקש בדיקה של ההטמעה, צריך למלא את טופס הערעור על התנאים וההגבלות של הפלטפורמה של מפות Google. תשובה תישלח אליך באימייל תוך כמה ימי עסקים.

RefererNotAllowedMapError שגיאה

כתובת ה-URL הנוכחית שטוענת את Maps JavaScript API לא נוספה לרשימת ההפניות המותרות. צריך לבדוק את הגדרות ההפניה של מפתח ה-API במסוף Cloud.

אפשר לעיין ב-Maps JavaScript API ולקבל מפתח API.
OverQuotaMapError שגיאה

מספר הבקשות חרג ממגבלות השימוש של Maps JavaScript API. הבקשות של האפליקציה יפעלו שוב באיפוס הבא של המכסה היומית.

אם אתם לא בעלי האתר, אין לכם אפשרות לתקן את השגיאה הזו. עם זאת, מומלץ להודיע לבעלי האתר אם אפשר.

לפרטים נוספים, קראו את המדריך בנושא מגבלות שימוש. בדף הזה מוסבר גם איך אפשר להגדיל את מכסות השימוש.

ApiProjectMapError שגיאה

לא הצלחנו לזהות את מפתח ה-API שצוין או את פרויקט ה-API שמשויך אליו. יכול להיות שהשגיאה היא זמנית. אם הודעת השגיאה הזו ממשיכה להופיע, יכול להיות שתצטרכו לקבל מפתח API חדש או ליצור פרויקט API חדש.

מידע נוסף זמין במאמר תחילת העבודה עם Google Maps Platform.
ClientIdLooksLikeCryptoKey אזהרה

יכול להיות שסיפקתם מפתח קריפטוגרפי בפרמטר client. צריך לציין את מזהה הלקוח בתור הפרמטר client. אין צורך להשתמש במפתח הקריפטוגרפי ב-Maps JavaScript API.

מדריך למזהי לקוח

ClientIdLooksLikeKey אזהרה

יכול להיות שסיפקתם מפתח API בפרמטר client. צריך לציין את מזהה הלקוח בתור הפרמטר client, או להשתמש בפרמטר key עם מפתח API חוקי במקום בפרמטר client.

מדריך למפתחות API ולמזהי לקוחות

InvalidChannel אזהרה

יכול להיות שציינת פרמטר channel לא חוקי. הערוץ חייב להיות מחרוזת אלפאנומרית ב-ASCII, שיכולה לכלול נקודה (.), קו תחתון (_) ומקף (-). חשוב לוודא שציינת פרמטר channel תקין.

מידע נוסף זמין במאמר דיווח | Google Maps Platform.

InvalidClientId אזהרה

נראה שהפרמטר client לא מכיל מזהה לקוח תקין. מזהה הלקוח צריך להתחיל ב-"gme-‎".

מדריך למפתחות API ולמזהי לקוחות

InvalidKey אזהרה

מפתח ה-API שכלול ברכיב הסקריפט שטוען את ה-API לא נראה תקין. חשוב לוודא שאתם משתמשים במפתח API תקין. אפשר ליצור מפתח API חדש במסוף Cloud.

כדי לקבל מפתח API, לוחצים על הכפתור שלמטה.
קדימה, מתחילים

InvalidVersion אזהרה

יכול להיות שציינתם מספר גרסה שגוי ברכיב הסקריפט. חשוב לוודא שאתם משתמשים במספר גרסה נכון.

מידע נוסף זמין במאמר ניהול גרסאות | Google Maps JavaScript API.

KeyLooksLikeClientId אזהרה

יכול להיות שסיפקתם מזהה לקוח כפרמטר key. צריך לציין את מזהה הלקוח כפרמטר client במקום הפרמטר key, או להשתמש בפרמטר key עם מפתח API תקין.

מדריך למפתחות API ולמזהי לקוחות

KeyLooksLikeCryptoKey אזהרה

יכול להיות שסיפקתם מפתח קריפטוגרפי או סוד חתימה כפרמטר key. צריך לציין את מזהה הלקוח כפרמטר client, ולהסיר את הפרמטר key מרכיב הסקריפט. המפתח הקריפטוגרפי לא נדרש ל-Maps JavaScript API. לחלופין, אפשר לקבל מפתח API במסוף Cloud ולהשתמש בפרמטר key.

אפשר לעיין במדריך בנושא ציון מזהה לקוח בזמן טעינת ה-API.

KeyLooksLikeProjectNumber אזהרה

יכול להיות שסיפקתם מספר פרויקט כפרמטר key. חשוב לוודא שאתם משתמשים במפתח API תקין. אפשר ליצור מפתח API חדש במסוף Cloud.

איך מקבלים מפתח API
NoApiKeys אזהרה

לרכיב הסקריפט שטוען את ה-API אין מפתח API. חשוב לוודא שכללת מפתח API תקין כפרמטר key. אפשר ליצור מפתח API חדש במסוף Cloud.

כדי לקבל מפתח API, לוחצים על הכפתור שלמטה.
קדימה, מתחילים

אם אתם טוענים את Maps JavaScript API מהנתיב של גרסה 2 שהוצאה משימוש, תקבלו את האזהרה NoApiKeys, גם אם ציינתם את הפרמטר key. כדאי לעיין במדריך לשדרוג מגרסה 2 לגרסה 3 ולהעביר את האפליקציה ל-Maps JavaScript API גרסה 3.

RetiredVersion אזהרה

יכול להיות שסיפקתם גרסה שהוצאה משימוש ברכיב הסקריפט. כדי להשתמש באחת מהגרסאות הזמינות, צריך לעדכן את האפליקציה.

מידע נוסף זמין במאמר ניהול גרסאות | Google Maps JavaScript API.

SensorNotRequired אזהרה

הפרמטר sensor כבר לא נדרש ב-Maps JavaScript API. הוא לא ימנע מ-Maps JavaScript API לפעול בצורה תקינה, אבל מומלץ להסיר את הפרמטר sensor מרכיב הסקריפט.

SignatureNotRequired אזהרה

הפרמטר signature לא נדרש ב-Maps JavaScript API. הוא לא ימנע מ-Maps JavaScript API לפעול כמו שצריך, אבל הוא עלול לגרום לסיכוני אבטחה. צריך להסיר אותו מרכיב הסקריפט.

SignedInNotSupported אזהרה

הפרמטר signed_in הוצא משימוש ואין בו תמיכה בגרסה של Maps JavaScript API שבה אתם משתמשים. הפעולה הזו לא תמנע מ-Maps JavaScript API לפעול, אבל יכול להיות שההתנהגות של האפליקציה תשתנה אם אתם מסתמכים על תכונות שדורשות כניסה לחשבון.

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]

אתם יכולים לעיין בטבלת קודי השגיאה שלמעלה כדי למצוא את קוד השגיאה שמופיע בהודעת השגיאה. אפשר גם למצוא פרטים על הודעת השגיאה במסמך ה-API שמקושר מההודעה.

הערה: אפשר להאזין לשגיאות אימות באופן פרוגרמטי.

טיפול בדפדפנים לא נתמכים

מוודאים שגרסת הדפדפן שבה אתם משתמשים נתמכת על ידי Maps JavaScript API.

אם אתם מפתחים אפליקציה למחשב עם Windows שפועלת ב-WebView, ודאו שאתם משתמשים ב-WebView2 שמבוסס על Edge. אין יותר תמיכה בגרסאות קודמות של WebView שמבוססות על Internet Explorer.

אם הקוד עדיין לא עובד

כדי לעזור לכם להפעיל את קוד מפות Google, ברנדן קני ומנו מרקס מצביעים על כמה טעויות נפוצות ואיך לפתור את הבעיה בסרטון הזה.

  • מחפשים שגיאות הקלדה. חשוב לזכור ש-JavaScript היא שפה תלויית אותיות רישיות.
  • בודקים את הדברים הבסיסיים – חלק מהבעיות הנפוצות ביותר מתרחשות במהלך היצירה הראשונית של המפה. למשל:
    • מוודאים שציינתם את המאפיינים zoom ו-center באפשרויות המפה.
    • מוודאים שהצהרתם על רכיב div שבו המפה תופיע במסך.
    • מוודאים שלרכיב ה-div של המפה יש גובה. כברירת מחדל, רכיבי div נוצרים עם גובה 0, ולכן הם לא גלויים.
    אפשר לעיין בדוגמאות שלנו להטמעה לדוגמה.
  • כדי לזהות בעיות, אפשר להשתמש ב-JavaScript debugger, כמו הכלי שזמין בכלים למפתחים ב-Chrome. קודם כל, בודקים אם יש שגיאות בלוח JavaScript.
  • לפרסם שאלות ב-Stack Overflow. בדף התמיכה מפורטות הנחיות לניסוח שאלות טובות.