The Maps Static API may issue an error or warning when something goes wrong. This guide explains each error message, and provides further instructions for resolving errors.
In the case of an invalid request, the Maps Static API returns
4xx status code and a message describing the
problem. Below are examples of such error conditions. Note: This is not
a complete list of the possible errors. Please check the actual error code
and message returned by the API for details of specific problems.
|Example of error condition||Status code|
|The request includes an invalid parameter, or a required parameter is
missing. For example, the
|The API key included in the request is invalid.||
Errors that prevent a map from being displayed
If the request is valid, but another error occurs that prevents the map from being displayed, the Maps Static API returns either text or an error image instead of the map, depending on the error. An example of such an error condition is when the application exceeds its usage limits.
Errors related to API keys and billing
If you use the Maps Static API without an API key, or if billing is not enabled on your account, the page displays an error image instead of a map, with a link indicating the type of error. For example "g.co/staticmaperror/key".
|Keyless errors and solutions|
|You are using the Maps Static API without an API key. To resolve, you must:|
|Your request is missing a digital signature (required). To resolve, Sign your URL|
For some error conditions, the API returns a map but some information may be missing from the map. When this happens, two conditions occur to inform you of the warning.
- One, the map displays, but with a yellow error bar superimposed over top of the map with the text "Map error: g.co/staticmaperror".
- Two, the API returns a warning in
the form of an HTTP header named
For example, the following URL contains an unexpected value in the
The API returns a map, but displays a yellow error bar superimposed over the image with "Map error: g.co/staticmaperror":
The API also returns the following HTTP header:
X-Staticmap-API-Warning:Error geocoding: marker 1
The following table describes the warnings that the API may issue as HTTP headers:
||An error occurred while attempting to geocode the request. There are
many variants of this message, depending on the element where geocoding
failed (center, marker, visible, or path) and the number of elements
that failed. One example of this warning is
||The request specifies more than the allowed maximum number of markers with a human readable address. The maximum is 15. Note that this limit applies only to markers specified as a human-readable address that requires geocoding. It does not apply to markers specified with latitude/longitude coordinates.|
||The request specifies more than the allowed maximum number of polylines with a human readable address. The maximum is 15. Note that this limit applies only to polylines with vertices specified as human-readable addresses that require geocoding. It does not apply to polylines specified with latitude/longitude coordinates.|
You can see the HTTP header warnings in the Chrome DevTools Console, the Firefox Web Console, or other equivalent tools in your browser.