이 페이지에서는 Maps JavaScript API에서 반환하는 오류 메시지를 설명합니다. Maps JavaScript API는 JavaScript 콘솔에 오류 및 경고 메시지를 표시합니다. 특정 오류 조건이 발생하여 워터마크가 표시된 어두운 지도가 표시될 수도 있습니다.
API 키 및 결제 오류
문제 해결
특정 상황에서는 '개발 전용'이라는 워터마크 텍스트와 함께 어두운 지도 또는 '음화' 스트리트 뷰 이미지가 표시될 수도 있습니다. 이 동작은 일반적으로 API 키 또는 결제 관련 문제를 나타냅니다. Google Maps Platform 제품을 사용하려면 계정에서 결제를 사용 설정해야 하고 모든 요청에 유효한 API 키를 포함해야 합니다. 오류 메시지를 찾는 방법에 관한 도움말은 브라우저에서 오류 확인 섹션에 있습니다.
다음 단계에 따라 문제를 해결할 수 있습니다.
개발자 및 사이트 소유자를 위한 Maps JavaScript API 오류 코드
다음 표에는 Maps JavaScript API에서 반환하는 가능한 오류 코드와 그 원인 및 문제 해결 방법이 나와 있습니다. 오류 메시지를 찾는 방법에 관한 도움말은 브라우저에서 오류 확인 섹션에 있습니다.
지도 로드 오류
Maps JavaScript API를 로드할 때 오류가 발생하면 아래의 표에서 오류 코드에 대한 설명을 확인하세요.
오류 코드 | 메시지 | 설명 |
---|---|---|
NotLoadingAPIFromGoogleMapsError
|
Google 서버에서 직접 Google Maps JavaScript API를 다운로드해야 합니다. |
Maps JavaScript API를 로드하는 스크립트 요소가 페이지에 올바르게 포함되지 않았습니다. API가 올바르게 작동하려면 https://maps.googleapis.com에서 직접 로드해야 합니다. Maps JavaScript API 로드를 참고하세요. |
TOSViolationMapError
|
이 웹사이트는 Google 지도 API 서비스 약관을 위반하는 것 같습니다. 이 웹사이트에서 Google 지도 API가 사용 중지되었습니다. |
애플리케이션이 이메일 알림을 여러 번 받은 후에도 Google Maps Platform 서비스 약관을 준수하지 않아 차단되었습니다. 차단에 이의를 신청하고 구현을 검토받으려면 이 양식을 작성하세요. 영업일 기준 며칠 이내에 이메일로 답장을 보내드립니다. Google Maps Platform 프리미엄 플랜 라이선스가 있는 경우 Google Maps Platform 프리미엄 플랜 사용자 인증 정보를 사용하여 이 오류를 해결하세요. 프리미엄 플랜 인증 가이드를 참고하세요. |
UnauthorizedURLForClientIdMapError
|
이 URL은 제공된 Google 지도 클라이언트 ID를 사용할 권한이 없습니다. |
스크립트 로드에 포함된 프리미엄 플랜 또는 업무용 지도 API 클라이언트 ID가 잘못되거나 만료되었거나, Maps JavaScript API를 로드하는 현재 주소가 승인된 URL 목록에 추가되지 않았습니다. 승인된 URL 등록하기를 참고하세요. |
Maps JavaScript API 오류 코드
Chrome JavaScript 콘솔, Firefox 웹 콘솔 또는 사용 중인 브라우저에서 이에 해당하는 기타 도구에서 오류를 발견한 경우 아래 표의 오류 코드에 대한 설명을 참고하세요.
Maps JavaScript API는 오류와 경고를 모두 반환합니다. 오류는 Maps JavaScript API를 로드하는 동안 발생한 심각한 문제를 나타냅니다. 페이지가 API를 올바로 로드하지 못하면 해당 페이지에서 API가 작동하지 않게 됩니다. 경고는 Maps JavaScript API 로드에 대한 추가 메시지입니다. 경고는 오류가 발생할 수 있는 이유를 설명하거나 Maps JavaScript API를 로드하는 코드에서 발생할 수 있는 문제를 알려줍니다. 오류 없이 경고만 반환되는 경우 API가 해당 페이지에서 올바르게 작동합니다. 하지만 이러한 잠재적 문제도 해결하는 것이 좋습니다.
개발자 오류 코드 | 유형 | 설명 |
---|---|---|
ApiNotActivatedMapError
|
오류 |
Maps JavaScript API가 API 프로젝트에서 활성화되지 않았습니다. Google Cloud 콘솔의 API에서 Maps JavaScript API를 사용 설정해야 할 수도 있습니다. 프로젝트에서 Maps JavaScript API를 활성화하려면 아래 버튼을 클릭하세요.
|
ApiTargetBlockedMapError
|
오류 |
이 API 키는 이 서비스 또는 API를 사용할 권한이 없습니다. 사용해야 하는 모든 API와 서비스가 사용 설정된 API 목록에 올바르게 지정되도록 하려면 Google Cloud 콘솔에서 API 키의 API 제한사항 설정을 확인하세요. Cloud 콘솔의 API 키를 참고하세요. 자세한 내용은 API 키 권장사항을 참고하세요. |
DeletedApiProjectMapError
|
오류 |
API 프로젝트가 Cloud 콘솔에서 삭제되었을 수도 있습니다. JavaScript API 로더에 포함된 API 키를 생성한 프로젝트를 확인하세요. Cloud 콘솔에서 새 API 프로젝트를 만들고 새 키를 가져올 수 있습니다. 새 프로젝트를 만들고 프로젝트의 API 키를 가져오려면 아래 버튼을 클릭하세요.
|
ClientBillingNotEnabledMapError
|
오류 |
프로젝트에 결제를 사용 설정하지 않았습니다. 여기에서 이 클라이언트 ID에 연결된 Google Cloud 프로젝트에 결제를 사용 설정해야 합니다. |
BillingNotEnabledMapError
|
오류 |
프로젝트에 결제를 사용 설정하지 않아 이 오류가 발생합니다. 여기에서 Google Cloud 프로젝트에 결제를 사용 설정해야 합니다. |
ExpiredKeyMapError
|
오류 |
API를 로드하는 스크립트 요소에 포함된 API 키가 만료되었거나 시스템에서 인식되지 않습니다. 새 API 키를 만든 후 시스템에서 키를 인식하기 전에 사용하려고 하면 이 오류가 발생할 수도 있습니다. 잠시 후 다시 시도하거나 Cloud 콘솔에서 새 API 키를 생성해야 할 수도 있습니다. API 키를 가져오려면 아래 버튼을 클릭하세요.
|
InvalidClientIdMapError
|
오류 |
API를 로드하는 스크립트 요소에 포함된 클라이언트 ID가 잘못되거나 만료되었습니다. 클라이언트 ID를 올바르게 사용하고 있는지 확인하세요. 클라이언트 ID는 'gme-' 접두사로 시작해야 합니다. 클라이언트 ID를 올바르게 사용하고 있는데도 이 오류가 표시된다면 클라이언트 ID가 만료되었을 수도 있습니다. Google 계정 관리자에게 문의하세요.
프리미엄 플랜 또는 업무용 지도 API 라이선스가 없는 경우 프리미엄 플랜 인증 가이드를 참고하세요. |
InvalidKeyMapError
|
오류 |
API를 로드하는 스크립트 요소에 포함된 API 키가 없습니다. 올바른 API 키를 사용하고 있는지 확인하세요. Cloud 콘솔에서 새 API 키를 생성할 수 있습니다. API 키를 가져오려면 아래 버튼을 클릭하세요.
|
MalformedCredentialsMapError
|
오류 |
애플리케이션에서 지원되지 않는 URI 스키마를 사용합니다. 애플리케이션에서 RFC 3986에 정의된 유효한 URI 형식을 사용하는지 확인하세요. |
MissingKeyMapError
|
오류 |
API를 로드하는 스크립트 요소에 필수 인증 매개변수가 누락되었습니다. 표준 Maps JavaScript API를 사용하는 경우 유효한 API 키와 함께 프리미엄 플랜 고객인 경우 웹사이트 소유자가 아닌 경우 이 오류를 해결하기 위해 취할 수 있는 방법이 없습니다. 하지만 가능한 경우 사이트 소유자에게 알려야 할 수도 있습니다. |
ProjectDeniedMapError
|
오류 |
요청이 완료되지 않았습니다. Cloud Console에서 오류에 대한 자세한 내용을 확인할 수도 있습니다. Cloud Console을 참고하세요. |
RefererDeniedMapError
|
오류 |
애플리케이션이 이메일 알림을 여러 번 받은 후에도 Google Maps Platform 서비스 약관을 준수하지 않아 차단되었습니다. 차단에 이의를 신청하고 구현을 검토받으려면 이 양식을 작성하세요. 영업일 기준 며칠 이내에 이메일로 답장을 보내드립니다. |
RefererNotAllowedMapError
|
오류 |
Maps JavaScript API를 로드하는 현재 URL이 허용된 리퍼러의 목록에 추가되지 않았습니다. Cloud 콘솔에서 API 키의 리퍼러 설정을 확인하세요. Maps JavaScript API와 API 키 가져오기를 참고하세요. |
OverQuotaMapError
|
오류 |
요청 수가 Maps JavaScript API의 사용량 한도를 초과했습니다. 일일 할당량이 재설정되면 앱의 요청이 다시 작동합니다. 웹사이트 소유자가 아닌 경우 이 오류를 해결하기 위해 취할 수 있는 방법이 없습니다. 하지만 가능한 경우 사이트 소유자에게 알리는 것이 좋습니다. 자세한 내용은 사용량 한도 가이드를 참고하세요. 이 페이지에서는 사용량 제한을 높이는 방법도 설명합니다. |
ApiProjectMapError
|
오류 |
제공된 API 키 또는 연결된 API 프로젝트를 확인하지 못했습니다. 이 오류는 일시적인 오류일 수도 있습니다. 이 오류 메시지가 계속 표시되면 새 API 키를 가져오거나 새 API 프로젝트를 만들어야 할 수도 있습니다. 자세한 내용은 Google Maps Platform 시작하기를 참고하세요. |
ClientIdLooksLikeCryptoKey
|
경고 |
프리미엄 플랜 및 업무용 지도 API 고객의 경우 클라이언트 ID 가이드를 참고하세요. |
ClientIdLooksLikeKey
|
경고 |
프리미엄 플랜 인증 가이드를 참고하세요. |
InvalidChannel
|
경고 |
잘못된 |
InvalidClientId
|
경고 |
프리미엄 플랜 인증 가이드를 참고하세요. |
InvalidKey
|
경고 |
API를 로드하는 스크립트 요소에 포함된 API 키가 잘못된 것 같습니다. 올바른 API 키를 사용하고 있는지 확인하세요. Cloud 콘솔에서 새 API 키를 생성할 수 있습니다. API 키를 가져오려면 아래 버튼을 클릭하세요.
|
InvalidVersion
|
경고 |
스크립트 요소에 잘못된 버전 번호를 제공했을 수도 있습니다. 올바른 버전 번호를 사용하고 있는지 확인하세요. |
KeyLooksLikeClientId
|
경고 |
클라이언트 ID를 key 매개변수로 제공했을 수도 있습니다. 프리미엄 플랜 또는 업무용 지도 API 라이선스가 있는 경우 클라이언트 ID를 key 매개변수 대신 client 매개변수로 지정하세요. Google Maps Platform 프리미엄 플랜을 이용하는 경우 client 매개변수 또는 key 매개변수를 사용할 수 있습니다. 라이선스가 없으면 client
매개변수 대신 key 매개변수를 사용해야 합니다.
프리미엄 플랜 인증 가이드를 참고하세요. |
KeyLooksLikeCryptoKey
|
경고 |
암호화 키 또는 서명 비밀번호를 API를 로드할 때 클라이언트 ID 지정 가이드를 참고하세요. |
KeyLooksLikeProjectNumber
|
경고 |
프로젝트 번호를 API 키를 가져오는 방법을 알아보세요. |
NoApiKeys
|
경고 |
API를 로드하는 스크립트 요소에 API 키가 없습니다. 유효한 API 키를
API 키를 가져오려면 먼저 아래 버튼을 클릭하세요.
지원 중단된 v2 경로에서 Maps JavaScript API를 로드하면 |
RetiredVersion
|
경고 |
스크립트 요소에 사용이 중단된 버전을 제공했을 수도 있습니다. 이용 가능한 버전 중 하나를 사용하도록 애플리케이션을 업데이트하세요. |
SensorNotRequired
|
경고 |
Maps JavaScript API에는 |
SignatureNotRequired
|
경고 |
Maps JavaScript API에는 |
SignedInNotSupported
|
경고 |
|
UrlAuthenticationCommonError
|
오류 |
이 페이지의 기타 카테고리에 맞지 않는 오류가 발생했습니다. 일시적인 문제로 인해 오류가 발생했을 수 있습니다. 잠시 후에 다시 요청하세요. 그래도 문제가 해결되지 않으면 개발자 가이드를 참고하여 요청의 형식이 올바른지 확인하세요. |
브라우저에서 오류 확인
Maps JavaScript API는 window.console
에 오류 메시지를 표시합니다. 이 섹션에서는 Chrome에서 window.console
출력을 확인하는 방법을 설명합니다. 다른 브라우저를 사용하는 경우 해당 브라우저의 개발자 문서를 참고하세요. 참고로 다음은 다른 브라우저에서 window.console
출력을 확인하는 도구의 목록입니다.
- Web Console(웹 콘솔)(Firefox)
- 원격 디버깅(Android)
- Web Inspector(웹 검사기)(iOS)
Chrome에서는 다음과 같이 JavaScript 콘솔을 사용하여 window.console
출력을 확인할 수 있습니다.
- 메뉴 아이콘 > 도구 더보기 > 개발자 도구를 선택하여 개발자 도구를 엽니다.
- 키보드에서 Esc 키를 눌러 JavaScript 콘솔을 엽니다. Esc 키를 누르면 JavaScript 콘솔로 전환됩니다. 콘솔을 닫은 경우 Esc 키를 눌러 엽니다.
Maps JavaScript API를 로드할 때 오류나 경고가 발생하면 콘솔에 하나 이상의 줄로 표시됩니다. 오류나 경고 메시지의 형식은 다음과 같습니다.
Google Maps API error: [ERROR CODE] [Link to API document]
또는
Google Maps API warning: [ERROR CODE] [Link to API document]
위의 오류 코드 표에서 오류 메시지의 오류 코드를 찾을 수 있습니다. 또한 메시지에 연결된 API 문서에서 오류 메시지에 대한 세부정보를 찾을 수 있습니다.
참고: 프로그래매틱 방식으로 인증 오류를 리슨할 수 있습니다.
지원되지 않는 브라우저 처리
현재 사용 중인 브라우저의 버전이 현재 Maps JavaScript API에서 지원되는지 확인하세요.
WebView에서 실행되는 기본 Windows 애플리케이션을 개발하는 경우 Edge를 기반으로 WebView2를 사용하세요. Internet Explorer를 기반으로 하는 이전 버전의 WebView는 더 이상 지원되지 않습니다.
그래도 코드가 작동하지 않는 경우
지도 코드를 작성하고 실행하는 데 도움이 되도록 Brendan Kenny와 Mano Marks가 다음 동영상에서 일반적인 실수 및 해결 방법을 알려줍니다.
- 오타를 찾습니다. JavaScript는 대소문자를 구분하는 언어입니다.
- 기본 사항을 확인합니다. 처음 지도를 만들 때 가장 일반적인 문제가 발생하는 경우가 있습니다. 예를 들면 다음과 같습니다.
- 지도 옵션에서
zoom
및center
속성을 지정했는지 확인합니다. - 화면에 지도를 표시할 div 요소를 선언했는지 확인합니다.
- 지도의 div 요소에 높이가 있는지 확인합니다. 기본적으로 div 요소는 높이가 0으로 생성되므로 표시되지 않습니다.
- 지도 옵션에서
- Chrome 개발자 도구에서 제공하는 디버거와 같은 JavaScript 디버거를 사용하여 문제를 식별합니다. 먼저 JavaScript 콘솔에서 오류를 찾아보세요.
- Stack Overflow에 질문을 게시합니다. 적절한 질문을 게시하는 방법에 관한 가이드라인은 지원 페이지를 확인하세요.