錯誤訊息
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本頁面說明 Maps Embed API 可能傳回的錯誤訊息。發生錯誤時，Maps Embed API 會以錯誤訊息文字取代地圖。此外，也可能發生某些錯誤狀況，導致出現加上浮水印的深色地圖。
無效的請求
如果要求無效，Maps Embed API 會傳回 HTTP 4xx 狀態碼，以及描述問題的訊息。以下是錯誤情況的範例。注意：這份清單僅列出部分可能的錯誤。請查看 API 傳回的實際錯誤代碼和訊息，瞭解特定問題的詳細資訊。
| 錯誤狀況示例 |
狀態碼 |
要求含有無效參數，或缺少必要參數。例如，zoom 參數不在預期的數值範圍內，或是要求的參數未出現在要求中。 |
400 BAD REQUEST |
| 要求中包含的 API 金鑰無效。 |
403 FORBIDDEN |
API 金鑰和配額錯誤
API 金鑰和配額錯誤會視為無效要求。可能的原因如下：
結帳和 HTTP 參照網址錯誤
發生下列任一情況時，系統會傳回顏色較深 (有點像「負片」效果的街景服務圖片)，而且會有「僅供開發使用」浮水印：
在瀏覽器中檢查錯誤
對於結算和 HTTP 參照網址錯誤，Maps Embed API 會將錯誤訊息寫入 window.console。對於無效的要求 (包括 API 金鑰和配額錯誤)，主控台只會回報 HTTP 4xx 狀態碼。本節說明如何查看 Google Chrome 的控制台輸出內容。如果您使用任何其他瀏覽器，請參閱瀏覽器的開發人員說明文件。以下列出在一些其他瀏覽器中查看控制台輸出內容時可使用的工具，供您參考。
在 Chrome 中，您可以使用 JavaScript 控制台檢查控制台輸出內容，如下所示。
-
如要開啟開發人員工具，請依序選取選單圖示 >「更多工具」 >「開發人員工具」。
-
如要開啟 JavaScript 控制台，請按一下開發人員工具視窗頂端的「主控台」分頁。您也可以使用 ESC 鍵切換 JavaScript 控制台。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-31 (世界標準時間)。
[null,null,["上次更新時間：2025-08-31 (世界標準時間)。"],[[["\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."]]
