Handling errors

European Economic Area (EEA) developers

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:

Possible causes:

The request is missing a valid API key.
Message: Your request cannot be served. Please ensure the parameters and request type are valid for your account and region.

2D satellite tiles are not available in projects that are linked to a billing account with a European Economic Area (EEA) address. For more information, see Map Tiles API adjustments for EEA customers.

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.
400: Invalid Value: Make sure that the mapType with which the createSessionToken request was made matches the mapType used in the subsequent tile endpoint. For example, a streetview session token cannot be used to request a roadmap tile.

403: Permission denied