הודעות שגיאה ב-Maps Static API

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

בקשות לא חוקיות

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

הבקשה כוללת פרמטר לא תקין, או שחסר פרמטר נדרש. לדוגמה, הפרמטר size לא נמצא בטווח הצפוי של ערכים מספריים, או שהוא חסר בבקשה.
400 BAD REQUEST
מפתח ה-API שכלול בבקשה לא תקין.
403 FORBIDDEN

שגיאות שמונעות את הצגת המפה

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

תמונת שגיאה מוצגת במקום מפה
תמונה של שגיאה מוצגת במקום מפה

אם אתם משתמשים ב-Maps Static API בלי מפתח API, או אם החיוב לא מופעל בחשבון שלכם, בדף מוצגת תמונת שגיאה במקום מפה, עם קישור שמציין את סוג השגיאה. לדוגמה, g.co/staticmaperror/key.

שגיאות שקשורות לשימוש ללא מפתח ופתרונות
שגיאה בטעינת מכסות השימוש: חריגה מהמגבלה היומית של טעינת מפות אתם משתמשים ב-Maps Static API ללא מפתח API. כדי לפתור את השגיאה, מבצעים את השלבים הבאים:
  1. קבלת מפתח API
  2. הפעלת החיוב
  3. חתימה על כתובת ה-URL
שגיאה בטעינת מכסות השימוש: בכתובות ה-URL של הבקשות חסרה חתימה דיגיטלית בבקשה שלך חסרה חתימה דיגיטלית נדרשת. כדי לפתור את השגיאה הזו, צריך לחתום על כתובת ה-URL.

אזהרות

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

  • המפה מוצגת עם פס שגיאה צהוב שמופיע מעל המפה עם הטקסט 'שגיאה במפה: g.co/staticmaperror'.
  • ה-API מחזיר אזהרה בצורה של כותרת HTTP בשם X-Staticmap-API-Warning.

לדוגמה, כתובת ה-URL הבאה מכילה ערך לא צפוי בפרמטר markers:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY

ה-API מחזיר מפה, אבל מוצג פס שגיאה צהוב שמופיע על התמונה עם הטקסט Map error: g.co/staticmaperror‎ (שגיאה במפה: g.co/staticmaperror):

המפה מופיעה עם השגיאה Map error: g.co/staticmaperror
מפה שמוצג בה פס אזהרה צהוב

ה-API מחזיר גם את כותרת ה-HTTP הבאה:

X-Staticmap-API-Warning:Error geocoding: marker 1

בטבלה הבאה מתוארות האזהרות שממשק ה-API יכול להנפיק ככותרות HTTP:

אזהרות בכותרות של X-Staticmap-API-Warning
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* קרתה שגיאה במהלך הניסיון לבצע גיאו-קידוד של הבקשה. יש הרבה גרסאות של ההודעה הזו, בהתאם לרכיב שבו הגיאו-קידוד נכשל, כמו center,‏ marker,‏ visible או path, ומספר הרכיבים שנכשלו. דוגמה לאזהרה כזו היא 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. המגבלה הזו חלה רק על קווי פוליגון עם קודקודים שצוינו ככתובות שניתנות לקריאה על ידי בני אדם, שנדרש להן גיאו-קידוד. הוא לא חל על קווי פוליגון שצוינו עם קואורדינטות של קו רוחב וקו אורך.

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