Mensagens de erro na API Maps Static

A API Maps Static emite um erro ou aviso quando uma solicitação falha. Este guia explica as mensagens de erro e fornece instruções para resolvê-las.

Solicitações inválidas

Para uma solicitação inválida, a API Maps Static retorna um código de status HTTP 4xx e uma mensagem que descreve o problema, conforme mostrado na lista a seguir. Verifique o código de erro e a mensagem retornados pela API para detalhes de problemas específicos.

A solicitação inclui um parâmetro inválido ou um parâmetro obrigatório está ausente. Por exemplo, o parâmetro size não está dentro do intervalo esperado de valores numéricos ou está ausente da solicitação.
400 BAD REQUEST
A chave de API incluída na solicitação é inválida.
403 FORBIDDEN

Erros que impedem a exibição de um mapa

Se a solicitação for válida, mas ocorrer outro erro que impeça a exibição do mapa, a API Maps Static vai retornar texto ou uma imagem de erro em vez do mapa. Por exemplo, um erro ocorre quando o aplicativo excede os limites de uso.

Imagem de erro exibida no lugar de um mapa
Uma imagem de erro é mostrada em vez de um mapa

Se você usar a API Maps Static sem uma chave de API ou se o faturamento não estiver ativado na sua conta, a página vai mostrar uma imagem de erro em vez de um mapa, com um link indicando o tipo de erro. Por exemplo, "g.co/staticmaperror/key".

Erros e soluções sem chave
Erro de limites de uso: o limite diário de carregamentos de mapas fornecido foi excedido Você está usando a API Maps Static sem uma chave de API. Para resolver esse erro, siga estas etapas:
  1. Gerar uma chave de API
  2. Ativar o faturamento
  3. Assinar seu URL
Erro de limites de uso: os URLs de solicitação não têm assinatura digital Sua solicitação não tem uma assinatura digital obrigatória. Para resolver esse erro, assine seu URL.

Avisos

Em algumas condições de erro, a API retorna um mapa, mas algumas informações podem estar faltando. Quando isso acontece, é possível identificar o aviso usando as seguintes condições:

  • O mapa aparece com uma barra de erro amarela sobreposta a ele com o texto "Erro no mapa: g.co/staticmaperror".
  • A API retorna um aviso na forma de um cabeçalho HTTP chamado X-Staticmap-API-Warning.

Por exemplo, o URL a seguir contém um valor inesperado no parâmetro markers:

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

A API retorna um mapa, mas mostra uma barra de erro amarela sobreposta na imagem com o texto "Erro no mapa: g.co/staticmaperror":

O mapa aparece com o erro: g.co/staticmaperror
Um mapa mostrando uma barra de aviso amarela

A API também retorna o seguinte cabeçalho HTTP:

X-Staticmap-API-Warning:Error geocoding: marker 1

A tabela a seguir descreve os avisos que a API pode emitir como cabeçalhos HTTP:

Alertas nos cabeçalhos X-Staticmap-API-Warning
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* Ocorreu um erro durante a tentativa de geocodificação da solicitação. Existem muitas variantes dessa mensagem, dependendo do elemento em que a geocodificação falhou, como center, marker, visible ou path, e do número de elementos que falharam. Um exemplo desse aviso é X-Staticmap-API-Warning:Error geocoding: marker 1, conforme mostrado no exemplo anterior.
Too many geocoded markers requested (max is 15). A solicitação especifica mais do que o número máximo permitido de marcadores com um endereço legível para humanos. A quantidade máxima é 15. Esse limite se aplica apenas a marcadores especificados como um endereço legível por humanos que exige geocodificação. Isso não se aplica a marcadores especificados com coordenadas de latitude e longitude.
Too many geocoded polyline vertices requested (max is 15). A solicitação especifica mais do que o número máximo permitido de polilinhas com um endereço legível para humanos. A quantidade máxima é 15. Esse limite se aplica apenas a polilinhas com vértices especificados como endereços legíveis por humanos que exigem geocodificação. Ela não se aplica a polilinhas especificadas com coordenadas de latitude e longitude.

É possível conferir os avisos de cabeçalho HTTP no console do Chrome DevTools, no console da Web do Firefox ou em outras ferramentas equivalentes no navegador.