오류 메시지
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 페이지에서는 Maps Embed API에서 반환할 수 있는 오류 메시지를 설명합니다. 오류가 발생하면 Maps Embed API는 지도 대신 오류 메시지 텍스트를 표시합니다.
특정 오류 조건이 발생하여 워터마크가 표시된 어두운 지도가 표시될 수도 있습니다.
잘못된 요청
잘못된 요청인 경우 Maps Embed API는 HTTP 4xx 상태 코드와 문제를 설명하는 메시지를 반환합니다. 다음은 오류 상태의 예입니다. 참고: 이 목록은 발생할 수 있는 오류의 전체 목록이 아닙니다. API에서 반환한 실제 오류 코드와 메시지를 확인하여 특정 문제에 관한 세부정보를 확인하세요.
| 오류 상황의 예 |
상태 코드 |
요청에 잘못된 매개변수가 포함되어 있거나 필수 매개변수가 누락되었습니다. 예를 들어 zoom 매개변수가 예상되는 숫자 값 범위에 해당하지 않거나 요청에 필수 매개변수가 누락된 경우입니다. |
400 BAD REQUEST |
| 요청에 포함된 API 키가 잘못되었습니다. |
403 FORBIDDEN |
API 키 및 할당량 오류
API 키 및 할당량 오류는 잘못된 요청으로 취급됩니다. 가능한 원인은 다음과 같습니다.
결제 및 HTTP 리퍼러 오류
다음 중 하나가 true인 경우 '개발 전용'이라는 워터마크가 표시된 어두운 지도 또는 '음화' 스트리트 뷰 이미지가 반환됩니다.
브라우저에서 오류 확인
결제 및 HTTP 리퍼러 오류의 경우 Maps Embed API는 window.console에 오류 메시지를 작성합니다. 잘못된 요청 (API 키 및 할당량 오류 포함)의 경우 HTTP 4xx 상태 코드만 콘솔에 보고됩니다. 이 섹션에서는 Chrome에서 콘솔 출력을 확인하는 방법을 설명합니다. 다른 브라우저를 사용하는 경우 해당 브라우저의 개발자 문서를 참고하세요. 참고로 다음은 다른 브라우저에서 콘솔 출력을 확인하는 도구의 목록입니다.
Chrome에서는 다음과 같이 JavaScript 콘솔을 사용하여 콘솔 출력을 확인할 수 있습니다.
-
메뉴 아이콘 > 도구 더보기 > 개발자 도구를 선택하여 개발자 도구를 엽니다.
-
JavaScript 콘솔을 열려면 개발자 도구 창 상단의 콘솔 탭을 클릭합니다. Esc 키를 사용하여 JavaScript 콘솔을 전환할 수도 있습니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-31(UTC)
[null,null,["최종 업데이트: 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."]]
