錯誤和疑難排解

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 分鐘)。系統會拒絕零 ("0s")、負值和低於 1 秒的值 (例如 "0.5s")。
    • 流量偏好設定：當 travelMode 為 WALK 或 BICYCLE 時，請確認 routingPreference 未設為 TRAFFIC_AWARE。即時流量僅支援 DRIVE 和 TWO_WHEELER。
    • 必要列舉：請務必指定 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 金鑰格式不正確或無法辨識，會傳回 400 INVALID_ARGUMENT，原因為 API_KEY_INVALID。
  • 403 PERMISSION_DENIED：驗證或授權失敗：
    • 要求中未提供驗證憑證 (X-Goog-Api-Key、?key= 或 Authorization: Bearer 權杖)。
    • 您的 Google Cloud 雲端專案未啟用 Isochrones API (isochrones.googleapis.com)，或未啟用計費功能。
    • 您的 API 金鑰設有 API 目標、IP 位址或 HTTP 參照網址限制，因此系統封鎖了傳送至 isochrones.googleapis.com 的要求。
  • 404 NOT_FOUND：無法解析起點，或無法貼齊道路網路：
    • 無法將place解析為位置。請確認地點 ID 有效且為最新。
    • 起點 location 或 place 群集中心與模式相容路段的距離，大於最大貼齊距離 (約 200 公尺，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：發生內部伺服器錯誤，例如後端逾時。以指數輪詢方式重試要求。