오류 및 문제 해결

Isochrones API는 표준 Google Cloud google.rpc.Status JSON 형식을 사용하여 오류를 반환합니다.

{
  "error": {
    "code": 400,
    "message": "Violation in GenerateIsochroneRequest.travel_duration: travel_duration must be at least 1 second and not exceed 3600 seconds (60 minutes) for DRIVE or TWO_WHEELER mode or 7200 seconds (120 minutes) for other modes",
    "status": "INVALID_ARGUMENT"
  }
}

status (또는 HTTP code) 필드를 사용하여 프로그래매틱 방식으로 오류를 처리합니다. message 텍스트는 개발자를 위한 것이며 변경될 수 있으므로 파싱하지 마세요.

Isochrones API를 사용할 때 다음과 같은 일반적인 오류 상태 코드가 발생할 수 있습니다.

  • 400 INVALID_ARGUMENT: 요청에 잘못된 매개변수 또는 잘못된 구문이 포함되어 있습니다.
    • 기간 경계: travelDuration가 "1s" 이상이고 "s"(예: "1800s")로 끝나며 모드 한도(DRIVE 및 TWO_WHEELER의 경우 3600s(60분), WALK 및 BICYCLE의 경우 7200s(120분))를 초과하지 않는지 확인합니다. 0 ("0s"), 음수 값, 1초 미만의 초 단위 값 (예: "0.5s")은 거부됩니다.
    • 트래픽 환경설정: travelMode가 WALK 또는 BICYCLE인 경우 routingPreference가 TRAFFIC_AWARE로 설정되지 않았는지 확인합니다. 실시간 트래픽은 DRIVE 및 TWO_WHEELER에서만 지원됩니다.
    • 필수 enum: travelMode 및 travelDirection(FROM 또는 TO)가 모두 지정되어 있고 *_UNSPECIFIED로 설정되어 있지 않은지 확인합니다.
    • 출발지 좌표 (location): latitude ([-90, 90]) 및 longitude ([-180, 180])를 모두 설정합니다. 생략된 필드는 오류 없이 0로 처리됩니다. 둘 다 생략하면 (0, 0)이 되어 거부됩니다. latitude만 생략하면 출발지가 적도에 배치되고 longitude만 생략하면 본초 자오선에 배치됩니다.
    • 장소 ID 형식 (place): place가 장소 ID 또는 places/{place_id} 리소스 이름 (예: "places/ChIJIQBpAG2ahYAR_6128GcTUEo")이고 추가 경로 세그먼트가 없으며 유효한 장소 ID를 참조하는지 확인합니다.
    • 필드 마스크 (X-Goog-FieldMask): 제공된 경우 헤더는 isochrone, isochrone.geoJson 또는 *와 같은 유효한 응답 경로를 참조해야 합니다.
    • 잘못된 API 키 (API_KEY_INVALID): X-Goog-Api-Key 또는 ?key=의 형식이 잘못되었거나 인식할 수 없는 API 키는 API_KEY_INVALID 이유와 함께 400 INVALID_ARGUMENT를 반환합니다.
  • 403 PERMISSION_DENIED: 인증 또는 승인 실패:
    • 요청에 사용자 인증 정보 (X-Goog-Api-Key, ?key= 또는 Authorization: Bearer 토큰)가 제공되지 않았습니다.
    • Isochrones API (isochrones.googleapis.com)가 Google Cloud 프로젝트에서 사용 설정되지 않았거나 결제가 사용 설정되지 않았습니다.
    • API 키에 isochrones.googleapis.com에 대한 요청을 차단하는 API 타겟, IP 주소 또는 HTTP 리퍼러 제한이 있습니다.
  • 404 NOT_FOUND: 출발지를 도로망으로 확인하거나 스냅할 수 없습니다.
    • place을(를) 위치로 확인할 수 없습니다. 장소 ID가 유효하고 최신 상태인지 확인합니다.
    • 출발지 location 또는 place 중심점이 모드 호환 도로 구간에서 최대 스냅 거리 (약 200m, WALK 및 BICYCLE의 경우 더 짧음)보다 멀리 떨어져 있습니다. 좌표를 공공 도로에 더 가깝게 이동하거나 대형 공원 또는 명소 장소 ID 대신 도로 입구 좌표를 전달하세요.
    • 좌표가 도로 데이터가 없는 지역 (예: 바다)에 있습니다.

  • 429 RESOURCE_EXHAUSTED: 프로젝트가 분당 할당량 한도 (기본값: 분당 요청 300개)를 초과했습니다.

    {
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Requests' and limit 'Requests per minute' of service 'isochrones.googleapis.com'.",
    "status": "RESOURCE_EXHAUSTED"
  }
}

    클라이언트 요청 비율을 제한하고 무작위 지터가 있는 지수 백오프를 사용하여 429 응답을 재시도합니다.

  • 503 UNAVAILABLE: 서비스를 일시적으로 사용할 수 없거나 과부하가 발생했습니다. 지수 백오프를 사용하여 요청을 다시 시도합니다.

  • 500 INTERNAL: 백엔드 제한 시간과 같은 내부 서버 오류가 발생했습니다. 지수 백오프를 사용하여 요청을 다시 시도합니다.