错误消息
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本页介绍了 Google 地图嵌入 API 可能会返回的错误消息。发生错误时，Google 地图嵌入 API 会显示错误消息文本，而不是地图。还可能会出现某些错误情况，导致显示暗色水印地图。
无效请求
如果请求无效，Google 地图嵌入 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 控制台，请点击“开发者工具”窗口顶部的 Console（控制台）标签页。您还可以使用 ESC 键切换 JavaScript 控制台。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-31。
[null,null,["最后更新时间 (UTC)：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."]]
