错误和问题排查

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 令牌）。
    • Isochrones API (isochrones.googleapis.com) 未在您的 Google Cloud 项目中启用，或者未启用结算功能。
    • 您的 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：发生内部服务器错误，例如后端超时。使用指数退避算法重试请求。