오류 처리

요청 후 오류 세부정보가 포함된 응답이 수신될 수 있습니다.

2D 타일 및 스트리트 뷰 이미지

다음 목록에는 2D 카드 및 스트리트 뷰 이미지를 사용할 때 발생할 수 있는 오류가 자세히 설명되어 있습니다.

오류 목록

다음 목록에는 Map Tiles API를 사용할 때 발생할 수 있는 오류가 자세히 설명되어 있습니다.

required
요청에 URL 매개변수가 누락되었습니다. 오류 메시지는 누락된 매개변수를 나타냅니다.
notFound, invalid

x, y 또는 z 값이 범위를 벗어났습니다.

  • 일반 지도 타일의 경우 최대 확대/축소 수준은 특정 지도 타일 및 요청한 지도 옵션에 따라 다릅니다.

  • 일반 지도 타일의 경우 x 좌표의 범위는 [0, (2^zoom)-1]이어야 합니다.

  • 일반 지도 타일의 경우 y 좌표의 범위는 [0, (2^(zoom-1))-1]이어야 합니다.

  • 스트리트 뷰 타일의 경우 확대/축소 레벨은 0과 5 사이여야 합니다.

  • 스트리트 뷰 타일의 경우 확대/축소 수준 5까지는 x 및 y 좌표 범위가 일반 지도 타일과 동일합니다. 이때 최대값은 imageHeight 또는 imagewidth를 tileHeight 또는 tileWidth로 나눈 값입니다.

forbidden: 요청에 유효한 API 키가 없습니다.

expired
session 토큰이 만료되었습니다. 세션 토큰은 생성된 시간부터 2주 동안 유효합니다. 이는 예고 없이 변경될 수 있습니다. 이 오류가 발생하면 세션 토큰 사용에 설명된 대로 새 세션 토큰을 가져와야 합니다.
badRequest

요청 형식이 잘못되었습니다. 일반적인 이유는 다음과 같습니다.

  • roadmap 레이어를 포함하지 않고 terrain 지도 유형을 지정했습니다.

  • 도로 지도가 아닌 지도 유형에 styles 배열을 포함했습니다.

  • 스트리트 뷰 메타데이터 요청에서 위도/경도 값과 파노라마 ID를 전송했습니다.

quotaExceeded, rateLimitExceeded

애플리케이션이 허용된 할당량을 초과했거나 허용된 초당 쿼리 수를 초과했습니다.

오류 예시

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "errors": [
      {
        "message": "The request is missing a valid API key.",
        "domain": "global",
        "reason": "forbidden"
      }
    ],
    "status": "PERMISSION_DENIED"
  }
}

재시도 요청

quotaExceeded 및 rateLimitExceeded로 요청이 실패하면 많은 클라이언트가 요청을 연속으로 재시도하려고 하므로 잘못된 요청이나 대규모 실패로 인해 Google 서버가 과부하되지 않도록 요청을 재시도해야 합니다. 즉, 요청을 재시도할 때 지수 백오프를 사용합니다. 지수 백오프를 사용하면 서버가 복구할 시간을 확보할 수 있도록 요청을 시간에 걸쳐 분산할 수 있습니다.

예를 들어 요청이 실패하면 1초 후에 다시 시도합니다. 이 시도도 실패하면 2초 후에 다시 요청을 재시도합니다. 이 요청도 실패하면 4초 후에 다시 시도합니다. 따라서 요청 간 시간을 두 배로 늘려 연속된 각 요청을 효과적으로 분산할 수 있습니다.

3D 타일

서버 오류를 처리하는 렌더기를 통해 실사 타일에 액세스하기 때문에 Google 서버의 오류는 명확하지 않을 수 있습니다.

카드 렌더러 오류

예를 들어 CesiumJS 렌더러는 일반적으로 서버 오류가 발생하면 자동으로 실패하므로 비정상 종료, 빈 화면, 특정 카드가 로드되지 않는 등의 문제가 발생할 수 있습니다.

서버 오류를 디버그하는 데 사용하는 기술은 사용하는 렌더기에 따라 다릅니다. CesiumJS와 같은 브라우저 기반 렌더러의 경우 대부분의 브라우저에 내장된 도구로 네트워크 트래픽을 검사할 수 있습니다. 예를 들어 Chrome DevTools를 사용할 수 있습니다.

일반적인 실수

다음 목록에는 발생할 수 있는 가장 일반적인 오류에 관한 세부정보가 포함되어 있습니다.

400: 잘못된 인수
잘못된 API 키, 쿼리 매개변수, 카드/카드 셋 ID 또는 만료된 세션 토큰
403: 권한 거부됨
API 키가 없거나 SSL 연결이 없거나 API 키가 3D 카드의 허용 목록에 추가되지 않았습니다. Map Tiles API의 3D Tiles 기능을 허용 목록에 추가하려면 프로젝트 ID를 포함하여 Google 지원팀에 문의하세요.
429: 요청한 횟수가 너무 많음
할당량이 소진되었습니다. Google 지원팀에 문의하여 할당량을 늘리세요.