Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)
Po wysłaniu prośby możesz otrzymać odpowiedź zawierającą szczegóły błędu.
Kafelki 2D i zdjęcia Street View
Poniżej znajdziesz listę błędów, które możesz napotkać podczas korzystania z płytki 2D i zdjęć Street View.
Lista błędów
Poniżej znajdziesz listę błędów, które mogą wystąpić podczas korzystania z Map Tiles API.
required
W Twoim żądaniu brakuje parametru adresu URL. Zwróć uwagę, że komunikat o błędzie wskazuje, którego parametru brakuje.
notFound, invalid
Wartości x, y lub z są spoza zakresu.
W przypadku zwykłych kafelków mapy maksymalny poziom powiększenia zależy od konkretnego kafelka i od opcji mapy, o które prosisz.
W przypadku zwykłych kafelków mapy współrzędna x musi mieścić się w zakresie [0, (2^zoom)-1].
W przypadku zwykłych kafelków mapy współrzędna y musi mieścić się w zakresie [0, (2^(zoom-1))-1].
W przypadku kafelków Street View poziom powiększenia musi mieścić się w zakresie od 0 do 5 (włącznie).
W przypadku fragmentów Street View zakresy współrzędnych x i y są takie same jak w przypadku zwykłych fragmentów mapy aż do poziomu powiększenia 5. W tym momencie maksymalne wartości to imageHeight lub imagewidth podzielone przez tileHeight lub tileWidth.
forbidden:
Możliwe przyczyny:
W żądaniu brakuje prawidłowego klucza interfejsu API.
Wiadomość: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
Twój token session wygasł. Token sesji jest ważny przez 2 tygodnie od momentu jego utworzenia. Pamiętaj, że może się to zmienić bez powiadomienia. Jeśli otrzymasz ten błąd, musisz uzyskać nowy token sesji zgodnie z opisem w sekcji Używanie tokenów sesji.
badRequest
Żądanie ma nieprawidłowy format. Oto częste powody:
Określono typ mapy terrain bez uwzględnienia warstwy roadmap.
W przypadku typu mapy innego niż mapa drogowa uwzględniono tablicę styles.
W żądaniu metadanych Street View przesłano wartość szerokości i długości geograficznej oraz identyfikator panoramy.
quotaExceeded, rateLimitExceeded
Aplikacja przekroczyła dozwolony limit lub dozwoloną liczbę zapytań na sekundę.
Przykładowy błąd
{"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"}}
Ponawianie żądań
Gdy żądania kończą się niepowodzeniem z kodami quotaExceeded i rateLimitExceeded, należy ponowić żądanie w taki sposób, aby uszkodzone żądania lub awarie na dużą skalę nie zalewały serwerów Google, ponieważ wielu klientów próbuje ponawiać żądania w szybkiej kolejności. Oznacza to, że podczas ponawiania żądań należy stosować odczekiwanie wykładnicze. Wycofywanie wykładnicze zmusza do rozłożenia żądań w czasie, aby serwer miał czas na odzyskanie sprawności.
Jeśli na przykład żądanie się nie powiedzie, spróbuj ponownie po sekundzie. Jeśli jednak ta próba również się nie powiedzie, ponów żądanie po 2 sekundach. Jeśli to żądanie również się nie powiedzie, spróbuj ponownie po 4 sekundach. W ten sposób skutecznie rozkładasz każde kolejne żądanie, po prostu podwajając czas między nimi.
Kafelki 3D
Błędy serwera Google mogą być dla Ciebie niewidoczne, ponieważ dostęp do fotorealistycznych kafelków uzyskujesz za pomocą renderera, który odpowiada za obsługę błędów serwera.
Błędy renderowania kafelków
Na przykład moduł renderujący CesiumJS zwykle nie zgłasza błędów serwera, co może powodować różne problemy, od awarii i pustych ekranów po brak wczytywania konkretnych kafelków.
Technika debugowania błędów serwera zależy od używanego renderera. W przypadku renderowania w przeglądarce, np. w CesiumJS, możesz sprawdzić ruch w sieci za pomocą narzędzi wbudowanych w większość przeglądarek. Możesz na przykład użyć Narzędzi deweloperskich w Chrome.
Typowe błędy
Poniżej znajdziesz szczegółowe informacje o najczęstszych błędach, które możesz napotkać.
400. Nieprawidłowy argument
Nieprawidłowe klucze interfejsu API, parametry zapytania, identyfikatory kafelka lub zestawu kafelków albo wygasły token sesji.
400. Nieprawidłowa wartość
Upewnij się, że parametr mapType, z którym wysłano createSessionToken żądanie, jest zgodny z parametrem mapType używanym w kolejnym punkcie końcowym kafelka. Na przykład tokena sesji a
streetview nie można użyć do wysłania prośby o kafelek roadmap.
403. Odmowa dostępu
Możliwe przyczyny:
Brak klucza interfejsu API, brak połączenia SSL lub klucz interfejsu API nie został dodany do listy dozwolonych w przypadku kafelków 3D. Skontaktuj się z zespołem pomocy Google i podaj identyfikator projektu, aby dodać go do listy dozwolonych w przypadku funkcji 3D Tiles interfejsu Map Tiles API.
Wiadomość: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
[null,null,["Ostatnia aktualizacja: 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."]]
