Hataları işleme
Koleksiyonlar ile düzeninizi koruyun
İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
Avrupa Ekonomik Alanı (AEA) geliştiricileri
İstek gönderdikten sonra, hata ayrıntılarını içeren bir yanıt alabilirsiniz.
2B parçalar ve Street View görüntüleri
Aşağıdaki listede, 2D Döşemeler ve Street View görüntülerini kullanırken karşılaşabileceğiniz hatalar ayrıntılı olarak açıklanmaktadır.
Listeleme hatası
Aşağıdaki listede, Harita Döşemeleri API'sini kullanırken karşılaşabileceğiniz hatalar ayrıntılı olarak açıklanmaktadır.
required- İsteğinizde bir URL parametresi eksik. Hata mesajında hangi parametrenin eksik olduğunun belirtildiğini unutmayın.
notFound, invalidx, y veya z değerleriniz aralık dışında.
Normal harita karoları için maksimum yakınlaştırma düzeyi, söz konusu harita karosuna ve istediğiniz harita seçeneklerine bağlıdır.
Normal harita döşemeleri için x koordinatı [0, (2^zoom)-1] aralığında olmalıdır.
Normal harita parçaları için y koordinatı [0, (2^(zoom-1))-1] aralığında olmalıdır.
Street View döşemeleri için yakınlaştırma değeri sıfır ile beş arasında (bu değerler dahil) olmalıdır.
Street View parçaları için x ve y koordinat aralıkları, beşinci düzey yakınlaştırmaya kadar normal harita parçalarıyla aynıdır. Bu noktada, maksimum değerler imageHeight veya imagewidth'nin tileHeight veya tileWidth'e bölünmesiyle elde edilir.
forbidden:
Olası nedenler:
İstek geçerli bir API anahtarı içermiyor.
Mesaj: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
2D uydu döşemeleri, Avrupa Ekonomik Alanı (AEA) adresine sahip bir faturalandırma hesabına bağlı projelerde kullanılamaz. Daha fazla bilgi için AEA'daki müşteriler için Harita Döşemeleri API'sinde yapılan düzenlemeler başlıklı makaleyi inceleyin.
expiredsession jetonunuzun süresi doldu. Oturum jetonunun geçerlilik süresi, oluşturulma zamanından itibaren iki haftadır. Bu durumun önceden haber verilmeksizin değişebileceğini unutmayın. Bu hatayı alırsanız Oturum jetonlarını kullanma bölümünde açıklandığı gibi yeni bir oturum jetonu almanız gerekir.badRequestİsteğinizin yapısı bozuktu. Bunun yaygın nedenleri arasında şunlar yer alır:
roadmap katmanı eklemeden terrain harita türü belirttiniz.
Yol haritası olmayan bir harita türü için styles dizisi eklediniz.
Bir Street View meta veri isteğinde enlem/boylam değeri ve panorama kimliği gönderdiniz.
quotaExceeded, rateLimitExceededUygulamanız izin verilen kotayı veya saniye başına izin verilen sorgu sayısını aştı.
Örnek hata
{
"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"
}
}
İstekleri yeniden deneme
İstekler quotaExceeded ve rateLimitExceeded ile başarısız olduğunda, bozuk isteklerin veya geniş çaplı hataların Google sunucularını doldurmaması için isteğinizi yeniden denemelisiniz. Birçok istemci, istekleri hızlı bir şekilde yeniden denemeye çalışır. Bu, isteklerinizi yeniden denerken eksponansiyel geri yükleme kullanmanız gerektiği anlamına gelir. Üstel geri çekilme, sunucuya toparlanması için zaman tanımak amacıyla isteklerinizi zaman içinde yaymanızı zorunlu kılar.
Örneğin, bir istek başarısız olursa bir saniye sonra tekrar deneyin. Ancak bu deneme de başarısız olursa iki saniye sonra isteğinizi tekrar deneyin. Bu istek de başarısız olursa dört saniye sonra tekrar deneyin. Bu nedenle, aralarındaki süreyi iki katına çıkararak her bir sonraki isteği etkili bir şekilde yayabilirsiniz.
3B parçalar
Google'ın sunucusundan kaynaklanan hatalar, sunucu hatalarını işlemekten sorumlu olan bir oluşturucu aracılığıyla fotogerçekçi döşemelere eriştiğiniz için sizin için belirgin olmayabilir.
Döşeme oluşturucu hataları
Örneğin, sunucu hataları oluştuğunda CesiumJS oluşturucusu genellikle sessizce başarısız olur. Bu durum, kilitlenmelerden boş ekranlara ve belirli kutucukların yüklenmemesine kadar çeşitli sorunlara yol açabilir.
Sunucu hatalarını ayıklamak için kullandığınız teknik, kullandığınız oluşturucuya bağlıdır. CesiumJS gibi tarayıcı tabanlı oluşturucularda, çoğu tarayıcıda yerleşik olarak bulunan araçlarla ağ trafiğini inceleyebilirsiniz. Örneğin, Chrome Geliştirici Araçları'nı kullanabilirsiniz.
Yaygın görülen hatalar
Aşağıdaki listede, karşılaşabileceğiniz en yaygın hatalarla ilgili ayrıntılar yer almaktadır.
- 400: Geçersiz bağımsız değişken
- Geçersiz API anahtarları, sorgu parametreleri, döşeme/döşeme grubu kimlikleri veya süresi dolmuş bir oturum jetonu.
- 400: Geçersiz Değer
createSessionToken isteğinin yapıldığı mapType'ın, sonraki döşeme uç noktasında kullanılan mapType ile eşleştiğinden emin olun. Örneğin, streetview oturum jetonu, roadmap döşemesi istemek için kullanılamaz.
403: İzin reddedildi
Olası nedenler:
API anahtarı eksik, SSL bağlantısı eksik veya API anahtarınız 3D Döşemeler için izin verilenler listesine eklenmemiş. Map Tiles API'nin 3D Tiles işlevinin izin verilenler listesine eklenmek için proje kimliğinizle Google Destek Ekibi ile iletişime geçin.
Mesaj: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
Fotoğraf gerçekliğinde 3D döşemeler, Avrupa Ekonomik Alanı (AEA) adresine sahip bir faturalandırma hesabına bağlı projelerde kullanılamaz. Daha fazla bilgi için AEA'daki müşteriler için Harita Döşemeleri API'sinde yapılan düzenlemeler başlıklı makaleyi inceleyin.
- 429: Çok fazla istek var
- Kotanız tükendi. Kotanızı artırmak için Google Destek Ekibi ile iletişime geçin.
Aksi belirtilmediği sürece bu sayfanın içeriği Creative Commons Atıf 4.0 Lisansı altında ve kod örnekleri Apache 2.0 Lisansı altında lisanslanmıştır. Ayrıntılı bilgi için Google Developers Site Politikaları'na göz atın. Java, Oracle ve/veya satış ortaklarının tescilli ticari markasıdır.
Son güncelleme tarihi: 2025-08-29 UTC.
[null,null,["Son güncelleme tarihi: 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."]]
