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
, orz
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
orimagewidth
divided bytileHeight
ortileWidth
.
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 aroadmap
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.