Xử lý lỗi
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)
Sau khi đưa ra yêu cầu, bạn có thể nhận được phản hồi có chứa thông tin chi tiết về lỗi.
Ô 2D và hình ảnh trong Chế độ xem đường phố
Danh sách sau đây trình bày chi tiết những lỗi mà bạn có thể gặp phải khi sử dụng 2D Tiles và hình ảnh Chế độ xem đường phố.
Lỗi khi liệt kê
Danh sách sau đây trình bày chi tiết các lỗi mà bạn có thể gặp phải khi sử dụng Map Tiles API.
required- Yêu cầu của bạn thiếu một tham số URL. Lưu ý rằng thông báo lỗi cho biết tham số nào bị thiếu.
notFound, invalidGiá trị x, y hoặc z của bạn nằm ngoài phạm vi.
Đối với các ô bản đồ thông thường, mức thu phóng tối đa phụ thuộc vào ô bản đồ cụ thể và các lựa chọn về bản đồ mà bạn yêu cầu.
Đối với các ô bản đồ thông thường, toạ độ x phải nằm trong phạm vi [0, (2^zoom)-1].
Đối với các ô bản đồ thông thường, toạ độ y phải nằm trong phạm vi [0, (2^(zoom-1))-1].
Đối với các ô Chế độ xem đường phố, mức thu phóng phải nằm trong khoảng từ 0 đến 5.
Đối với Ô Chế độ xem đường phố, phạm vi toạ độ x và y giống như đối với ô bản đồ thông thường, cho đến khi đạt mức thu phóng 5. Tại thời điểm đó, giá trị tối đa là imageHeight hoặc imagewidth chia cho tileHeight hoặc tileWidth.
forbidden:
Nguyên nhân có thể có:
Yêu cầu thiếu một khoá API hợp lệ.
Tin nhắn: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
Các ô vệ tinh 2D không có trong những dự án được liên kết với một tài khoản thanh toán có địa chỉ ở Khu vực kinh tế Châu Âu (EEA). Để biết thêm thông tin, hãy xem bài viết Điều chỉnh Map Tiles API cho khách hàng ở Khu vực kinh tế Châu Âu (EEA).
expired- Mã thông báo
session của bạn đã hết hạn. Mã thông báo phiên có hiệu lực trong 2 tuần kể từ thời điểm tạo. Xin lưu ý rằng thông tin này có thể thay đổi mà không cần thông báo. Nếu gặp lỗi này, bạn phải lấy mã thông báo phiên mới, như mô tả trong phần Sử dụng mã thông báo phiên.
badRequestYêu cầu của bạn không đúng định dạng. Lỗi này thường xảy ra vì các nguyên nhân sau:
Bạn đã chỉ định loại bản đồ terrain mà không thêm lớp roadmap.
Bạn đã thêm một mảng styles cho loại bản đồ không phải là bản đồ đường đi.
Bạn đã gửi giá trị vĩ độ/kinh độ cũng như mã nhận dạng toàn cảnh trong một yêu cầu siêu dữ liệu của Chế độ xem đường phố.
quotaExceeded, rateLimitExceededỨng dụng của bạn đã vượt quá hạn mức được phép hoặc vượt quá số lượng truy vấn được phép mỗi giây.
Ví dụ về lỗi
{
"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"
}
}
Thử lại yêu cầu
Khi các yêu cầu không thành công với quotaExceeded và rateLimitExceeded, bạn nên thử lại yêu cầu theo cách mà các yêu cầu bị hỏng hoặc lỗi trên diện rộng không làm tràn ngập máy chủ của Google – vì nhiều ứng dụng cố gắng thử lại các yêu cầu liên tiếp. Điều này có nghĩa là bạn phải sử dụng thuật toán thời gian đợi luỹ thừa khi thử lại các yêu cầu. Thời gian đợi luỹ thừa buộc bạn phải trải đều các yêu cầu theo thời gian để máy chủ có thời gian khôi phục.
Ví dụ: nếu một yêu cầu không thành công, hãy thử lại sau một giây. Nhưng nếu lần thử đó cũng không thành công, hãy thử lại yêu cầu sau 2 giây. Nếu yêu cầu đó cũng không thành công, hãy thử lại sau 4 giây. Vì vậy, bạn có thể trải đều từng yêu cầu liên tiếp bằng cách chỉ cần tăng gấp đôi khoảng thời gian giữa các yêu cầu.
Ô 3D
Bạn có thể không nhận thấy các lỗi từ máy chủ của Google vì bạn truy cập vào các ô có độ chân thực cao thông qua một trình kết xuất. Trình kết xuất này chịu trách nhiệm xử lý các lỗi máy chủ.
Lỗi trình kết xuất ô
Ví dụ: trình kết xuất CesiumJS thường gặp lỗi âm thầm khi xảy ra lỗi máy chủ, điều này có thể dẫn đến mọi thứ, từ sự cố, màn hình trống cho đến các ô cụ thể không tải được.
Kỹ thuật mà bạn sử dụng để gỡ lỗi máy chủ sẽ phụ thuộc vào trình kết xuất cụ thể mà bạn sử dụng. Đối với các trình kết xuất dựa trên trình duyệt như CesiumJS, bạn có thể kiểm tra lưu lượng truy cập mạng bằng các công cụ được tích hợp trong hầu hết các trình duyệt. Ví dụ: bạn có thể sử dụng Công cụ của Chrome cho nhà phát triển.
Lỗi phổ biến
Danh sách sau đây chứa thông tin chi tiết về những lỗi thường gặp nhất mà bạn có thể gặp phải.
- 400: Đối số không hợp lệ
- Khoá API, tham số truy vấn, mã nhận dạng ô/tập hợp ô không hợp lệ hoặc mã thông báo phiên đã hết hạn.
- 400: Giá trị không hợp lệ
- Đảm bảo rằng mapType mà yêu cầu
createSessionToken được thực hiện khớp với mapType được dùng trong điểm cuối ô tiếp theo. Ví dụ: bạn không thể dùng mã thông báo phiên streetview để yêu cầu một ô roadmap.
403: Quyền bị từ chối
Nguyên nhân có thể có:
Thiếu khoá API, thiếu kết nối SSL hoặc bạn chưa thêm khoá API vào danh sách cho phép cho Ô 3D. Hãy liên hệ với Nhóm hỗ trợ của Google bằng mã dự án của bạn để được thêm vào danh sách cho phép đối với chức năng Ô 3D của Map Tiles API.
Tin nhắn: Your request cannot be served. Please ensure the parameters and
request type are valid for your account and region.
Ô 3D siêu thực không có trong các dự án được liên kết với tài khoản thanh toán có địa chỉ ở Khu vực kinh tế Châu Âu (EEA). Để biết thêm thông tin, hãy xem bài viết Điều chỉnh Map Tiles API cho khách hàng ở Khu vực kinh tế Châu Âu (EEA).
- 429: Quá nhiều yêu cầu
- Hạn mức của bạn đã hết. Hãy liên hệ với Nhóm hỗ trợ Google để tăng hạn mức.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-29 UTC.
[null,null,["Cập nhật lần gần đây nhất: 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."]]
