טיפול בשגיאות
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
מפתחים באזור הכלכלי האירופי (EEA)
אחרי שליחת הבקשה, יכול להיות שתקבלו תשובה עם פרטים על השגיאה.
משבצות דו-ממדיות ותמונות Street View
ברשימה הבאה מפורטות השגיאות שבהן יכול להיות שתיתקלו כשמשתמשים ב-2D Tiles ובתמונות Street View.
רשימת שגיאות
ברשימה הבאה מפורטות השגיאות שיכולות להופיע כשמשתמשים ב-Map Tiles API.
required- בבקשה שלך חסר פרמטר של כתובת URL. שימו לב שהודעת השגיאה מציינת
איזה פרמטר חסר.
notFound, invalidהערכים של x, y או z הם מחוץ לטווח.
במשבצות מפה רגילות, רמת הזום המקסימלית תלויה במשבצת המפה הספציפית ובאפשרויות המפה שביקשתם.
במשבצות מפה רגילות, קואורדינטת ה-x צריכה להיות בטווח [0, (2^zoom)-1].
בקטעי מפה רגילים, קואורדינטת ה-y צריכה להיות בטווח [0, (2^(zoom-1))-1].
במשבצות של Street View, רמת הזום צריכה להיות בין אפס לחמש, כולל.
באריחי Street View, טווחי הקואורדינטות x ו-y זהים לטווחי הקואורדינטות של אריחי מפה רגילים, עד לזום ברמה חמש. בשלב הזה, הערכים המקסימליים הם imageHeight או imagewidth חלקי tileHeight או tileWidth.
forbidden:
סיבות אפשריות:
בבקשה חסר מפתח API תקין.
הודעה: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
משבצות לוויין דו-ממדיות לא זמינות בפרויקטים שמקושרים לחשבון לחיוב עם כתובת באזור הכלכלי האירופי (EEA). מידע נוסף זמין במאמר התאמות ב-Map Tiles API ללקוחות באזור הכלכלי האירופי.
expired- פג התוקף של הטוקן שלך ל-
session. התוקף של טוקן סשן הוא שבועיים מזמן היצירה שלו. שימו לב: יכול להיות שיהיו שינויים במגבלות האלה ללא הודעה מוקדמת. אם אתם מקבלים את השגיאה הזו, אתם צריכים לקבל אסימון סשן חדש, כמו שמתואר במאמר שימוש באסימוני סשן.
badRequestהבקשה שלך הייתה בעלת מבנה פגום. בין הסיבות הנפוצות לכך:
ציינת סוג מפה terrain בלי לכלול שכבת roadmap.
הוספתם מערך styles לסוג מפה שאינו מפת דרכים.
שלחתם ערך של קו רוחב/קו אורך, וגם מזהה פנורמה בבקשה למטא-נתונים של Street View.
quotaExceeded, rateLimitExceededהאפליקציה חרגה מהמיכסה המותרת או ממספר השאילתות המותר לשנייה.
דוגמה לשגיאה
{
"error": {
"code": 403,
"message": "The request is missing a valid API key.",
"errors": [
{
"message": "The request is missing a valid API key.",
"domain": "global",
"reason": "forbidden"
}
],
"status": "PERMISSION_DENIED"
}
}
ניסיון חוזר של בקשות
אם הבקשות נכשלות עם קודי השגיאה quotaExceeded ו-rateLimitExceeded, צריך לנסות לשלוח שוב את הבקשה באופן שלא יגרום להצפת השרתים של Google בבקשות פגומות או בכשלים נרחבים – כי לקוחות רבים מנסים לשלוח שוב בקשות ברצף מהיר. כלומר, צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר כשמנסים לשלוח שוב את הבקשות. השהיה מעריכית לפני ניסיון חוזר (exponential backoff) מאלצת אתכם לפזר את הבקשות לאורך זמן, כדי לתת לשרת זמן להתאושש.
לדוגמה, אם בקשה נכשלת, צריך לנסות שוב אחרי שנייה אחת. אבל אם גם הניסיון הזה נכשל, צריך לנסות שוב את הבקשה אחרי שתי שניות. אם גם הבקשה הזו נכשלת, צריך לנסות שוב אחרי ארבע שניות. כך למעשה, כדי להרחיק את הבקשות זו מזו, פשוט מכפילים את משך הזמן בין כל בקשה לבקשה.
3D Tiles
יכול להיות שלא תראו שגיאות מהשרת של Google כי אתם ניגשים למשבצות פוטו-ריאליסטיות דרך רכיב עיבוד, שאחראי לטיפול בשגיאות בשרת.
שגיאות ברינדור של משבצות
לדוגמה, בדרך כלל, רכיב ה-Renderer של CesiumJS נכשל בשקט כשמתרחשות שגיאות בשרת, מה שיכול לגרום לכל דבר, החל מקריסות ומסכים ריקים ועד לטעינה של משבצות ספציפיות.
הטכניקה שבה משתמשים כדי לנפות באגים בשגיאות שרת תלויה ברכיב העיבוד הספציפי שבו משתמשים. במעבדי רינדור מבוססי-דפדפן כמו CesiumJS, אפשר לבדוק את תנועת הרשת באמצעות כלים שמובנים ברוב הדפדפנים. לדוגמה, אפשר להשתמש בכלי הפיתוח ל-Chrome.
שגיאות נפוצות
הרשימה הבאה כוללת פרטים על השגיאות הנפוצות ביותר שבהן אתם עשויים להיתקל.
- 400: ארגומנט לא תקין
- מפתחות API לא תקינים, פרמטרים של שאילתות, מזהים של משבצות או של ערכות משבצות, או טוקן של סשן שפג תוקפו.
- 400: ערך לא חוקי
- חשוב לוודא שסוג המפה (mapType) שבו נעשתה הבקשה
createSessionToken זהה לערך mapType שמשמש בנקודת הקצה של המשבצת הבאה. לדוגמה, אי אפשר להשתמש באסימון סשן של streetview כדי לבקש משבצת של roadmap.
403: Permission denied
סיבות אפשריות:
מפתח API חסר, חיבור SSL חסר או שמפתח ה-API לא נוסף לרשימת ההיתרים של 3D Tiles. כדי להוסיף אתכם לרשימת ההיתרים של הפונקציונליות של 3D Tiles ב-Map Tiles API, צריך לפנות אל תמיכת Google עם מזהה הפרויקט.
הודעה: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
אי אפשר להשתמש בטקסטורות תלת-ממדיות פוטוריאליסטיות בפרויקטים שמקושרים לחשבון לחיוב עם כתובת באזור הכלכלי האירופי (EEA). מידע נוסף זמין במאמר התאמות ב-Map Tiles API ללקוחות באזור הכלכלי האירופי.
- 429: יותר מדי בקשות
- הגעת למכסה. כדי להגדיל את המכסה, צריך לפנות אל התמיכה של Google.
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-29 (שעון UTC).
[null,null,["עדכון אחרון: 2025-08-29 (שעון UTC)."],[[["\u003cp\u003eRequests for 2D Tiles and Street View imagery may result in errors such as \u003ccode\u003erequired\u003c/code\u003e, \u003ccode\u003enotFound\u003c/code\u003e, \u003ccode\u003einvalid\u003c/code\u003e, \u003ccode\u003eforbidden\u003c/code\u003e, \u003ccode\u003eexpired\u003c/code\u003e, \u003ccode\u003ebadRequest\u003c/code\u003e, \u003ccode\u003equotaExceeded\u003c/code\u003e, or \u003ccode\u003erateLimitExceeded\u003c/code\u003e indicating issues with parameters, API keys, or quota limits.\u003c/p\u003e\n"],["\u003cp\u003eWhen retrying requests that failed due to \u003ccode\u003equotaExceeded\u003c/code\u003e or \u003ccode\u003erateLimitExceeded\u003c/code\u003e, it's crucial to implement exponential backoff to avoid overwhelming Google servers.\u003c/p\u003e\n"],["\u003cp\u003e3D Tiles errors are often handled by the renderer, requiring debugging techniques like inspecting network traffic using browser developer tools.\u003c/p\u003e\n"],["\u003cp\u003eCommon 3D Tiles errors include 400 (Invalid argument), 403 (Permission denied), and 429 (Too many requests), which can be addressed by verifying API keys, SSL connections, allowlisting, or adjusting quotas.\u003c/p\u003e\n"]]],["Upon encountering errors when using Map Tiles API, common issues include missing URL parameters (`required`), out-of-range coordinates (`notFound`, `invalid`), an invalid API key (`forbidden`), or an expired session token (`expired`). Other errors involve malformed requests (`badRequest`) or exceeding usage limits (`quotaExceeded`, `rateLimitExceeded`). When rate limiting occurs, implement exponential backoff when retrying requests. 3D Tiles errors may be handled by the renderer and include issues like invalid keys, missing API key, or exceeded quota.\n"],null,["# Handling errors\n\n**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google\n| Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. [Learn more](/maps/comms/eea/faq). In addition, certain content from the Map Tiles API will no longer be returned. [Learn more](/maps/comms/eea/map-tiles).\n\nAfter you make a request, you might receive a response that contains error\ndetails.\n\n2D Tiles and Street View imagery\n--------------------------------\n\nThe following list details the errors that you might encounter when using 2D\nTiles and Street View imagery.\n\n### Error listing\n\nThe following list details the errors you might encounter when using the\nMap Tiles API.\n\n`required`\n: Your request is missing a URL parameter. Note that the error message indicates\n which parameter is missing.\n\n`notFound`, `invalid`\n\n: Your \u003cvar class=\"apiparam\" translate=\"no\"\u003e\u003ccode translate=\"no\" dir=\"ltr\"\u003ex\u003c/code\u003e\u003c/var\u003e, \u003cvar class=\"apiparam\" translate=\"no\"\u003e\u003ccode translate=\"no\" dir=\"ltr\"\u003ey\u003c/code\u003e\u003c/var\u003e, or\n \u003cvar class=\"apiparam\" translate=\"no\"\u003e\u003ccode translate=\"no\" dir=\"ltr\"\u003ez\u003c/code\u003e\u003c/var\u003e values are out of range.\n\n - For regular map tiles, the maximum zoom level depends on the particular\n map tile, and on the map options that you requested.\n\n - For regular map tiles, the x coordinate must be in the range\n \\[0, (2\\^zoom)-1\\].\n\n - For regular map tiles, the y coordinate must be in the range\n \\[0, (2\\^(zoom-1))-1\\].\n\n - For Street View Tiles, zoom must be between zero and five, inclusive.\n\n - For Street View Tiles, the x and y coordinate ranges are the same as\n for regular map tiles, until level five zoom. At that point, the maximum\n values are `imageHeight` or `imagewidth` divided by `tileHeight` or\n `tileWidth`.\n\n`forbidden`:\n\nPossible causes:\n\n- The request is missing a valid API key.\n\n- Message: `Your request cannot be served. Please ensure the parameters and\n request type are valid for your account and region.`\n\n 2D satellite tiles are not available in projects that are linked to a\n billing account with a European Economic Area (EEA) address. For more\n information, see [Map Tiles API adjustments for EEA\n customers](/maps/comms/eea/map-tiles#adjustments).\n\n`expired`\n: Your `session` token has expired. A session token is valid for\n two weeks from its creation time. Note that this might change\n without notice. If you receive this error, then you must get a new session\n token, as described in\n [Use session tokens](/maps/documentation/tile/session_tokens).\n\n`badRequest`\n\n: Your request was malformed. Common reason for this include:\n\n - You specified a `terrain` map type without including a `roadmap` layer.\n\n - You included a `styles` array for a non-roadmap map type.\n\n - You sent a lat/lng value, as well as a panorama ID in a Street View metadata\n request.\n\n`quotaExceeded`, `rateLimitExceeded`\n\n: Your application has exceeded its allowed quota, or it exceeded it allowed\n number of queries per second.\n\n### Example error\n\n {\n \"error\": {\n \"code\": 403,\n \"message\": \"The request is missing a valid API key.\",\n \"errors\": [\n {\n \"message\": \"The request is missing a valid API key.\",\n \"domain\": \"global\",\n \"reason\": \"forbidden\"\n }\n ],\n \"status\": \"PERMISSION_DENIED\"\n }\n }\n\n### Retrying requests\n\nWhen requests fail with `quotaExceeded` and `rateLimitExceeded`, you should\nretry your request in such as way that broken requests or wide-scale failures\ndon't flood Goodle servers---as many clients attempt to retry requests in quick\nsuccession. This means using\n[exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)\nwhen you retry your requests. Exponential backoff forces you to spread your\nrequests out in time, to give the server time to recover.\n\nFor example, if a request fails, then retry again after one second. But if that\nattempt fails as well, then retry your request again after two seconds. If that\nrequest also fails, then try again after four seconds. So you effectively spread\neach successive request out by simply doubling the length of time between them.\n\n3D Tiles\n--------\n\nErrors from Google's server might not be obvious to you because you access\nphotorealistic tiles through a renderer, which is responsible for handling\nserver errors.\n\n### Tile renderer errors\n\nFor example, the CesiumJS renderer usually fails silently when server errors\noccur, which can result in anything from crashes, blank screens, to specific\ntiles not loading.\n\nThe technique that you use to debug server errors will depend on the particular\nrenderer you use. For browser-based renderers like CesiumJS, you can inspect\nthe network traffic with tools built into most browsers. For example, you can\nuse\n[Chrome DevTools](https://developer.chrome.com/docs/devtools/).\n\n### Common errors\n\nThe following list contains details about the most common errors that you might\nencounter.\n\n400: Invalid argument\n: Invalid API keys, query parameters, tile/tileset IDs, or an expired session\n token.\n\n400: Invalid Value\n: Make sure that the mapType with which the `createSessionToken` request was\n made matches the `mapType` used in the subsequent tile endpoint. For example, a\n `streetview` session token cannot be used to request a `roadmap` tile.\n\n**403: Permission denied**\n\nPossible causes:\n\n- Missing API key, missing SSL connection, or your API key has not been added\n to the allowlist for 3D Tiles. Contact [Google\n Support](/maps/support#contact-maps-support) with your project ID to get\n added to the allowlist for the 3D Tiles functionality of the\n Map Tiles API.\n\n- Message: `Your request cannot be served. Please ensure the parameters and\n request type are valid for your account and region.`\n\n Photorealistic 3D tiles are not available in projects that are linked to a\n billing account with a European Economic Area (EEA) address. For more\n information, see [Map Tiles API adjustments for EEA\n customers](/maps/comms/eea/map-tiles#adjustments).\n\n429: Too many requests\n: Your quota is exhausted. Contact\n [Google Support](/maps/support#contact-maps-support) to increase your quota."]]
