session 토큰이 만료되었습니다. 세션 토큰은 생성 시간으로부터 2주 동안 유효합니다. 이 내용은 사전 통지 없이 변경될 수 있습니다. 이 오류가 표시되면 세션 토큰 사용에 설명된 대로 새 세션 토큰을 가져와야 합니다.
badRequest
요청 형식이 잘못되었습니다. 일반적인 이유는 다음과 같습니다.
roadmap 레이어를 포함하지 않고 terrain 지도 유형을 지정했습니다.
로드맵이 아닌 지도 유형에 styles 배열을 포함했습니다.
스트리트 뷰 메타데이터 요청에서 위도/경도 값과 파노라마 ID를 전송했습니다.
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 서버를 과부하하지 않도록 요청을 재시도해야 합니다. 즉, 요청을 다시 시도할 때 지수 백오프를 사용해야 합니다. 지수 백오프를 사용하면 서버가 복구할 시간을 확보할 수 있도록 요청을 시간별로 분산해야 합니다.
예를 들어 요청이 실패하면 1초 후에 다시 시도합니다. 하지만 이 시도도 실패하면 2초 후에 요청을 다시 시도하세요. 이 요청도 실패하면 4초 후에 다시 시도합니다. 따라서 요청 간 시간을 두 배로 늘리면 각 후속 요청을 효과적으로 분산할 수 있습니다.
3D 타일
Google 서버의 오류는 서버 오류 처리를 담당하는 렌더러를 통해 사실적인 타일에 액세스하므로 명확하지 않을 수 있습니다.
타일 렌더러 오류
예를 들어 CesiumJS 렌더러는 일반적으로 서버 오류가 발생할 때 자동으로 실패하므로 비정상 종료, 빈 화면, 특정 타일이 로드되지 않는 등 다양한 문제가 발생할 수 있습니다.
서버 오류를 디버깅하는 데 사용하는 기술은 사용하는 특정 렌더러에 따라 달라집니다. CesiumJS와 같은 브라우저 기반 렌더러의 경우 대부분의 브라우저에 내장된 도구를 사용하여 네트워크 트래픽을 검사할 수 있습니다. 예를 들어 Chrome DevTools를 사용할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(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."]]
