Thông báo 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.
Trang này mô tả các thông báo lỗi mà API nhúng Maps có thể trả về. Khi xảy ra lỗi, API nhúng Maps sẽ hiển thị văn bản thông báo lỗi thay vì bản đồ.
Một số điều kiện lỗi cũng có thể xảy ra, dẫn đến việc bản đồ có hình mờ bị tối.
Yêu cầu không hợp lệ
Trong trường hợp yêu cầu không hợp lệ, API nhúng Maps sẽ trả về một mã trạng thái 4xx HTTP và một thông báo mô tả vấn đề. Dưới đây là ví dụ về các điều kiện lỗi. Lưu ý: Đây không phải là danh sách đầy đủ các lỗi có thể xảy ra. Kiểm tra mã lỗi thực tế và thông báo do API trả về để biết thông tin chi tiết về các vấn đề cụ thể.
| Ví dụ về điều kiện lỗi |
Mã trạng thái |
Yêu cầu có một tham số không hợp lệ hoặc thiếu một tham số bắt buộc. Ví dụ: tham số zoom không nằm trong phạm vi giá trị số dự kiến hoặc thiếu một tham số bắt buộc trong yêu cầu. |
400 BAD REQUEST |
| Khoá API trong yêu cầu là không hợp lệ. |
403 FORBIDDEN |
Lỗi hạn mức và khoá API
Lỗi khoá API và lỗi hạn mức được coi là yêu cầu không hợp lệ. Một số nguyên nhân có thể là:
Lỗi thanh toán và lỗi liên quan đến HTTP referer
Hệ thống sẽ trả về một bản đồ bị làm tối hoặc hình ảnh "âm" của Chế độ xem đường phố, có hình mờ"chỉ dành cho mục đích phát triển" khi xảy ra một trong những trường hợp sau:
Kiểm tra lỗi trong trình duyệt
Đối với lỗi liên quan đến Billing và HTTP referer, API nhúng Maps sẽ ghi thông báo lỗi vào window.console. Đối với các yêu cầu không hợp lệ (bao gồm cả lỗi khoá API và hạn mức), chỉ mã trạng thái HTTP 4xx mới được báo cáo trong bảng điều khiển. Phần này giải thích cách bạn có thể kiểm tra đầu ra của bảng điều khiển trong Google Chrome. Nếu bạn đang sử dụng trình duyệt nào khác, vui lòng tham khảo tài liệu dành cho nhà phát triển về trình duyệt của bạn. Để bạn tham khảo, sau đây là danh sách các công cụ để kiểm tra đầu ra của bảng điều khiển trong một số trình duyệt khác.
Trong Chrome, bạn có thể sử dụng Bảng điều khiển JavaScript để kiểm tra kết quả của bảng điều khiển như sau.
-
Để mở Công cụ dành cho nhà phát triển, hãy chọn biểu tượng trình đơn > Công cụ khác >
Công cụ dành cho nhà phát triển.
-
Để mở Bảng điều khiển JavaScript, hãy nhấp vào thẻ Console (Bảng điều khiển) ở đầu cửa sổ Công cụ cho nhà phát triển. Bạn cũng có thể dùng phím ESC để bật/tắt Console JavaScript.
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-31 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-31 UTC."],[[["\u003cp\u003eThe Maps Embed API displays error messages in place of the map or as a darkened, watermarked map when errors occur.\u003c/p\u003e\n"],["\u003cp\u003eInvalid requests result in a \u003ccode\u003e4xx\u003c/code\u003e HTTP status code and a descriptive error message, often due to missing or incorrect parameters or an invalid API key.\u003c/p\u003e\n"],["\u003cp\u003eAPI key and quota errors are treated as invalid requests, and can stem from a missing, invalid, or restricted API key, or a disabled API.\u003c/p\u003e\n"],["\u003cp\u003eBilling and HTTP referer errors result in a darkened, watermarked map, and may be caused by billing issues, exceeding usage limits, or missing HTTP referers.\u003c/p\u003e\n"],["\u003cp\u003eError messages for billing and referer issues can be found in the browser's console; invalid request errors show only the HTTP status code.\u003c/p\u003e\n"]]],["The Maps Embed API displays error messages or a watermarked map when issues occur. Invalid requests trigger a `4xx` status code, indicating problems like missing or incorrect parameters or an invalid API key. Billing or HTTP referer issues result in a watermarked map, caused by disabled billing, invalid payment, exceeded limits, or missing referers. Errors are logged in the browser's console (`window.console`) and can be checked via browser developer tools.\n"],null,["This page describes the error messages that can be returned by the\nMaps Embed API. When an error occurs, the\nMaps Embed API presents error message text in place of the map.\nCertain error conditions may also occur, which result in the display of a\ndarkened watermarked map.\n\nInvalid requests\n\nIn the case of an invalid request, the Maps Embed API returns\nan HTTP `4xx` status code and a message describing the\nproblem. Below are examples of error conditions. Note: This is not\na complete list of the possible errors. Check the actual error code\nand message returned by the API for details of specific problems.\n\n| Example of error condition | Status code |\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|\n| The request includes an invalid parameter, or a required parameter is missing. For example, the `zoom` parameter is not within the expected range of numeric values, or a required parameter is missing from the request. | `400 BAD REQUEST` |\n| The API key included in the request is invalid. | `403 FORBIDDEN` |\n\nAPI key and quota errors\n\nAPI key and quota errors are treated as invalid requests. Possible causes\ninclude the following:\n\n- Missing or invalid API key. To resolve this error, ensure that your request includes a valid API key. [Get an API key](/maps/documentation/embed/get-api-key#get-an-api-key).\n- Maps Embed API is not enabled for your project. Learn about [enabling and disabling APIs](https://cloud.google.com/apis/docs/enable-disable-apis).\n- API key has a restriction violation. [Read\n more about API key best practices](/maps/api-key-best-practices).\n\nBilling and HTTP referer errors\n\nA darkened map, or \"negative\" Street View image, watermarked with \"for\ndevelopment purposes only\" is returned when any of the following is true:\n\n- Billing has not been enabled on your account. [Enable billing](https://console.cloud.google.com/project/_/billing/enable?utm_source=Docs_BillingNudge).\n- The provided billing method is invalid (for example an expired credit card). To resolve this, visit the [Google Cloud console, and ensure that you have provided a valid method of payment.](https://console.cloud.google.com/project/_/billing)\n- A self-imposed daily limit has been exceeded. [Learn how to view or change daily billable limits](/maps/documentation/embed/usage-and-billing#set-caps).\n- The request is missing an HTTP referer, and you are using a referer-restricted API key. [Learn\n more about adding referers](/maps/api-key-best-practices).\n\nCheck errors in your browser\n\nFor Billing and HTTP referer errors, the Maps Embed API writes\nerror messages to `window.console`. For invalid requests (including\nAPI key and quota errors), only the HTTP `4xx` status code is reported\nin the console. This section explains how you can check the console output in\nGoogle Chrome. If you are using any other browsers, please check the developer\ndocumentation for your browser. For your reference, this is a list of tools to\ncheck console output in some other browsers.\n\n- [Console](https://msdn.microsoft.com/en-us/library/dn255006(v=vs.85).aspx) for Internet Explorer.\n- [Web Console](https://developer.mozilla.org/en-US/docs/Tools/Web_Console) for Firefox.\n- [Remote debugging](https://developer.chrome.com/devtools/docs/remote-debugging) for Android.\n- [Web Inspector](https://developer.apple.com/library/safari/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/GettingStarted/GettingStarted.html) for iOS.\n\n\nIn Chrome, you can use the\n[JavaScript Console](/web/tools/chrome-devtools/debug/console)\nto check console output as follows.\n\n1. To open the Developer Tools, select the menu icon \\\u003e **More Tools** \\\u003e **Developer Tools**.\n2. To open the JavaScript Console, click the **Console** tab at the top of the Developer Tools window. You can also use the ESC key to toggle the JavaScript Console."]]
