Handling errors

After you make a request, you might receive a response that contains error details.

2D Tiles and Street View imagery

The following list details the errors that you might encounter when using 2D Tiles and Street View imagery.

Error listing

The following list details the errors you might encounter when using the Map Tiles API.

required

Your request is missing a URL parameter. Note that the error message indicates which parameter is missing.

notFound, invalid

Your x, y, or z values are out of range.

• For regular map tiles, the maximum zoom level depends on the particular map tile, and on the map options that you requested.

• For regular map tiles, the x coordinate must be in the range [0, (2^zoom)-1].

• For regular map tiles, the y coordinate must be in the range [0, (2^(zoom-1))-1].

• For Street View Tiles, zoom must be between zero and five, inclusive.

• For Street View Tiles, the x and y coordinate ranges are the same as for regular map tiles, until level five zoom. At that point, the maximum values are imageHeight or imagewidth divided by tileHeight or tileWidth.

forbidden: The request is missing a valid API key.

expired

Your session token has expired. A session token is valid for two weeks from its creation time. Note that this might change without notice. If you receive this error, then you must get a new session token, as described in Use session tokens.

badRequest

Your request was malformed. Common reason for this include:

• You specified a terrain map type without including a roadmap layer.

• You included a styles array for a non-roadmap map type.

• You sent a lat/lng value, as well as a panorama ID in a Street View metadata request.

quotaExceeded, rateLimitExceeded

Your application has exceeded its allowed quota, or it exceeded it allowed number of queries per second.

Example error

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

Retrying requests

When requests fail with quotaExceeded and rateLimitExceeded, you should retry your request in such as way that broken requests or wide-scale failures don't flood Goodle servers—as many clients attempt to retry requests in quick succession. This means using exponential backoff when you retry your requests. Exponential backoff forces you to spread your requests out in time, to give the server time to recover.

For example, if a request fails, then retry again after one second. But if that attempt fails as well, then retry your request again after two seconds. If that request also fails, then try again after four seconds. So you effectively spread each successive request out by simply doubling the length of time between them.

3D Tiles

Errors from Google's server might not be obvious to you because you access photorealistic tiles through a renderer, which is responsible for handling server errors.

Tile renderer errors

For example, the CesiumJS renderer usually fails silently when server errors occur, which can result in anything from crashes, blank screens, to specific tiles not loading.

The technique that you use to debug server errors will depend on the particular renderer you use. For browser-based renderers like CesiumJS, you can inspect the network traffic with tools built into most browsers. For example, you can use Chrome DevTools.

Common errors

The following list contains details about the most common errors that you might encounter.

400: Invalid argument

Invalid API keys, query parameters, tile/tileset IDs, or an expired session token.

403: Permission denied

Missing API key, missing SSL connection, or your API key has not been added to the allowlist for 3D Tiles. Contact Google Support with your project ID to get added to the allowlist for the 3D Tiles functionality of the Map Tiles API.

429: Too many requests

Your quota is exhausted. Contact Google Support to increase your quota.