Errors and troubleshooting

The Isochrones API returns errors using the standard Google Cloud google.rpc.Status JSON format:

{
  "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"
  }
}

Use the status (or HTTP code) field to handle errors programmatically. The message text is intended for developers and might change, so don't parse it.

When working with the Isochrones API, you might encounter the following common error status codes:

• 400 INVALID_ARGUMENT: The request contains invalid parameters or malformed syntax:
  • Duration bounds: Make sure travelDuration is at least "1s", ends with "s" (such as "1800s"), and doesn't exceed the mode limit: 3600s (60 minutes) for DRIVE and TWO_WHEELER, or 7200s (120 minutes) for WALK and BICYCLE. Zero ("0s"), negative values, and sub-second values under 1 second (such as "0.5s") are rejected.
  • Traffic preference: Make sure routingPreference isn't set to TRAFFIC_AWARE when travelMode is WALK or BICYCLE. Live traffic is only supported for DRIVE and TWO_WHEELER.
  • Required enums: Ensure both travelMode and travelDirection (FROM or TO) are specified and aren't set to *_UNSPECIFIED.
  • Origin coordinates (location): Set both latitude (in [-90, 90]) and longitude (in [-180, 180]). An omitted field is treated as 0 without an error: omitting both gives (0, 0), which is rejected; omitting only latitude places the origin on the Equator; and omitting only longitude places it on the prime meridian.
  • Place ID format (place): Ensure place is a place ID or a places/{place_id} resource name (for example, "places/ChIJIQBpAG2ahYAR_6128GcTUEo"), with no extra path segments, and refers to a valid place ID.
  • Field mask (X-Goog-FieldMask): If provided, the header must reference valid response paths such as isochrone, isochrone.geoJson, or *.
  • Invalid API key (API_KEY_INVALID): A malformed or unrecognized API key in X-Goog-Api-Key or ?key= returns 400 INVALID_ARGUMENT with reason API_KEY_INVALID.
• 403 PERMISSION_DENIED: Authentication or authorization failed:
  • No authentication credentials (X-Goog-Api-Key, ?key=, or Authorization: Bearer token) were provided in the request.
  • The Isochrones API (isochrones.googleapis.com) isn't enabled on your Google Cloud project, or billing isn't enabled.
  • Your API key has API target, IP address, or HTTP referrer restrictions that block requests to isochrones.googleapis.com.
• 404 NOT_FOUND: The origin couldn't be resolved or snapped to the road network:
  • The place couldn't be resolved to a location. Check that the place ID is valid and current.
  • The origin location or place centroid lies farther from a mode-compatible road segment than the maximum snapping distance (about 200 meters, or less for WALK and BICYCLE). Move the coordinate closer to a public road or pass road-entrance coordinates instead of a large park or landmark place ID.
  • The coordinate is in an area without road data (such as open ocean).

• 429 RESOURCE_EXHAUSTED: Your project exceeded its per-minute quota limit (default 300 requests per minute):

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

  Throttle client request rates and retry 429 responses using exponential backoff with randomized jitter.

• 503 UNAVAILABLE: The service is temporarily unavailable or overloaded. Retry the request using exponential backoff.

• 500 INTERNAL: An internal server error occurred, such as a backend timeout. Retry the request using exponential backoff.