הודעות שגיאה

בדף הזה מתוארות הודעות השגיאה שיכולות להתקבל מ-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 יפעל בצורה תקינה, צריך לטעון אותו ישירות מכתובת ה-URL https://maps.googleapis.com.

טעינת Maps JavaScript API

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

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

כדי לפתור את השגיאה הזו, צריך להשתמש בפרטי הכניסה של מפתח ה-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 במסוף Google Cloud כדי לוודא שכל ממשקי ה-API והשירותים שאתם צריכים מופיעים בצורה נכונה ברשימת ממשקי ה-API המופעלים.

אפשר לעיין במאמר בנושא מפתחות 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, אחרי ששלחנו לך כמה התראות באימייל. כדי לערער על החסימה ולבקש בדיקה של ההטמעה, צריך למלא את הטופס הזה. תשובה תישלח אליך באימייל תוך כמה ימי עסקים.

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. במקום להשתמש בפרמטר key, צריך לציין את מזהה הלקוח כפרמטר client, או להשתמש בפרמטר 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. היא לא תמנע מממשק ה-API של JavaScript במפות Google לפעול בצורה תקינה, אבל היא עלולה ליצור סיכוני אבטחה. צריך להסיר אותו מרכיב הסקריפט.

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.

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

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

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