HTML5 Geolocation PositionError 객체가 반환하는 오류 코드 총정리

HTML5의 Geolocation API를 사용해 사용자 위치를 조회할 때, 다양한 이유로 위치 정보를 가져오지 못하는 경우가 발생합니다. 이때 getCurrentPosition() 또는 watchPosition() 메서드의 오류 콜백 함수에는 PositionError 객체가 전달되며, 이 객체의 code 속성을 통해 실패 원인을 확인할 수 있습니다.

PositionError 오류 코드 목록

PositionError 객체가 반환하는 오류 코드는 아래와 같습니다.

오류 코드별 상세 설명

0. UNKNOWN_ERROR (알 수 없는 오류)

그 외에 분류되지 않은 원인으로 위치 조회가 실패한 경우입니다. 브라우저나 기기 내부의 예기치 못한 문제로 인해 발생할 수 있습니다.

1. PERMISSION_DENIED (권한 거부)

사용자가 브라우저에서 위치 정보 접근을 거부했거나, 애플리케이션에 위치 서비스 사용 권한이 부여되지 않은 경우 발생합니다. 가장 흔히 접하는 오류로, 사용자에게 권한 허용을 안내하는 것이 좋습니다.

2. POSITION_UNAVAILABLE (위치 확인 불가)

GPS, Wi-Fi, 네트워크 등 어떤 방법으로도 기기의 위치를 판별할 수 없는 경우 발생합니다. 실내 환경이나 신호가 약한 지역에서 자주 나타날 수 있습니다.

3. TIMEOUT (시간 초과)

PositionOptions의 timeout 옵션으로 설정한 시간 내에 위치 정보를 받아오지 못한 경우 발생합니다. 네트워크 상태가 불안정하거나 위치 확인이 지연될 때 발생합니다.

활용 예제

다음은 오류 콜백에서 PositionError 객체의 코드와 메시지를 확인하는 간단한 예제입니다.

navigator.geolocation.getCurrentPosition(
  function(position) {
    console.log('위도: ' + position.coords.latitude);
    console.log('경도: ' + position.coords.longitude);
  },
  function(error) {
    switch (error.code) {
      case error.PERMISSION_DENIED:
        console.log('위치 정보 접근 권한이 거부되었습니다.');
        break;
      case error.POSITION_UNAVAILABLE:
        console.log('현재 위치를 확인할 수 없습니다.');
        break;
      case error.TIMEOUT:
        console.log('위치 정보 요청 시간이 초과되었습니다.');
        break;
      default:
        console.log('알 수 없는 오류가 발생했습니다.');
    }
  }
);

또한 PositionError 객체의 message 속성을 함께 활용하면, 사람이 읽기 쉬운 형태의 오류 설명을 사용자에게 제공할 수 있어 디버깅과 UX 개선에 도움이 됩니다.