Error messages in Maps Static API

  • The Maps Static API returns errors as HTTP status codes or warning messages for invalid requests, usage limits, or issues with API keys and billing.

  • Errors that prevent map display can result in error images or text messages instead of the map, with details provided in the response.

  • Warnings about potential issues, like geocoding problems or marker limits, are indicated by a yellow error bar on the map and HTTP header warnings.

  • For invalid requests, refer to the HTTP status code (e.g., 400, 403) and message for details about the specific issue.

  • Always check for HTTP header warnings and the yellow error bar to ensure your map is displayed correctly and address potential issues.

The Maps Static API issues an error or warning when a request fails. This guide explains the error messages and provides instructions for resolving them.

Invalid requests

For an invalid request, the Maps Static API returns an HTTP 4xx status code and a message describing the problem, as shown in the following list. Check the actual error code and message returned by the API for details of specific problems.

The request includes an invalid parameter, or a required parameter is missing. For example, the size parameter isn't within the expected range of numeric values, or is missing from the request.
400 BAD REQUEST
The API key included in the request is invalid.
403 FORBIDDEN

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. For example, an error occurs when the application exceeds its usage limits.

Error image displayed instead of a map
An error image displayed instead of a map

If you use the Maps Static API without an API key, or if billing isn't 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
Usage limits error: exceeded provided daily map loads limit You're using the Maps Static API without an API key. To resolve this error, complete the following steps:
  1. Get an API key
  2. Enable billing
  3. Sign your URL
Usage limits error: request URLs are missing the digital signature Your request is missing a required digital signature. To resolve this error, sign your URL.

Warnings

For some error conditions, the API returns a map, but some information might be missing from the map. When this occurs, you can identify the warning by using the following conditions:

  • The map appears with a yellow error bar superimposed on the map with the text "Map error: g.co/staticmaperror."
  • The API returns a warning in the form of an HTTP header named X-Staticmap-API-Warning.

For example, the following URL contains an unexpected value in the markers parameter:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY

The API returns a map, but displays a yellow error bar superimposed on the image with the text "Map error: g.co/staticmaperror":

Map appears with Map error: g.co/staticmaperror
A map displaying a yellow warning bar

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 can issue as HTTP headers:

Warnings in X-Staticmap-API-Warning headers
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* An error occurred while attempting to geocode the request. Many variants of this message exist, depending on the element where geocoding failed, such as center, marker, visible, or path, and the number of elements that failed. One example of this warning is X-Staticmap-API-Warning:Error geocoding: marker 1, as shown in the preceding example.
Too many geocoded markers requested (max is 15). The request specifies more than the allowed maximum number of markers with a human-readable address. The maximum is 15. This limit applies only to markers specified as a human-readable address that requires geocoding. It doesn't apply to markers specified with latitude and longitude coordinates.
Too many geocoded polyline vertices requested (max is 15). The request specifies more than the allowed maximum number of polylines with a human-readable address. The maximum is 15. This limit applies only to polylines with vertices specified as human-readable addresses that require geocoding. It doesn't apply to polylines specified with latitude and 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.