Mensagens de erro

Nesta página, descrevemos as mensagens de erro que a API Maps JavaScript pode retornar. Ela grava mensagens de erro e aviso no Console JavaScript. Algumas condições de erro também podem ocorrer, o que resulta na apresentação de um mapa com marca-d'água escurecido.

Chave de API e erros de faturamento

Solução de problemas

Em algumas situações, um mapa escurecido ou uma imagem "negativa" do Street View pode aparecer com a marca d'água "somente para fins de desenvolvimento". Normalmente, isso indica problemas com uma chave de API ou com o faturamento. Para usar os produtos da Plataforma Google Maps, o faturamento precisa estar ativado na sua conta, e todas as solicitações têm que incluir uma chave de API válida. Se precisar de ajuda para encontrar mensagens, consulte a seção sobre como verificar erros no navegador.

Confira neste fluxo como resolver o problema.

Códigos de erro da API Maps JavaScript para desenvolvedores e proprietários de sites

As tabelas a seguir mostram os possíveis códigos de erro retornados pela API Maps JavaScript, uma descrição da causa e como você pode corrigir o problema. Se precisar de ajuda para encontrar as mensagens, consulte a seção sobre como verificar erros no navegador.

Erros no carregamento de mapa

Se ocorrer um erro ao carregar a API Maps JavaScript, consulte as explicações dos códigos de erro na tabela a seguir.

Código do erro Mensagem Descrição
NotLoadingAPIFromGoogleMapsError Faça o download da API Maps JavaScript diretamente dos servidores do Google.

O elemento de script que carrega a API Maps JavaScript não está sendo incluído corretamente na sua página. Carregue a API diretamente de https://maps.googleapis.com para que ela funcione.

Consulte Carregar a API Maps JavaScript.

TOSViolationMapError A API Google Maps foi desativada nesse site porque ele parece violar os Termos de Serviço da API.

Após várias notificações por e-mail, seu aplicativo foi bloqueado por estar em desacordo com os Termos de Serviço da Plataforma Google Maps. Para contestar o bloqueio e pedir uma revisão da implementação, preencha este formulário. Você vai receber uma resposta por e-mail dentro de alguns dias úteis.

Caso você tenha uma licença do Plano Premium da Plataforma Google Maps, use suas credenciais para resolver esse erro. Consulte o guia sobre autenticação do Plano Premium.

UnauthorizedURLForClientIdMapError Esse URL não está autorizado a usar o ID de cliente do Google Maps informado.

O ID do Plano Premium ou das APIs Maps for Work incluído no carregamento do script é inválido, está vencido ou o endereço carregando a API Maps JavaScript não está na lista de URLs autorizados.

Consulte Registrar URLs autorizados.

Códigos de erro da API Maps JavaScript

Consulte na tabela abaixo as explicações para os códigos de erro que podem ocorrer no Console JavaScript do Chrome, no console da Web do Firefox ou em qualquer outra ferramenta equivalente nos navegadores.

A API Maps JavaScript retorna erros e avisos. Erros indicam um problema grave que ocorreu ao carregar a API. A API não foi carregada corretamente e não vai funcionar na página. Avisos são mensagens complementares sobre o carregamento da API. Eles descrevem alguns motivos para um erro ou sugerem possíveis problemas no código que carrega a API. A API funciona corretamente na página quando identifica apenas avisos e nenhum erro. No entanto, recomendamos que você também corrija esses possíveis problemas.

Código de erro do desenvolvedor Tipo Descrição
ApiNotActivatedMapError Erro

A API Maps JavaScript não está ativada no seu projeto de API. Faça a ativação em "APIs", no console do Google Cloud.

Para ativar a API no projeto, clique no botão abaixo.
Saiba como

ApiTargetBlockedMapError Erro

A chave de API não está autorizada a usar este serviço ou API. No console do Google Cloud, verifique as configurações de Restrições da API da sua chave para garantir que todas as APIs e serviços necessários estejam especificados corretamente na lista de APIs ativadas.

Consulte Chaves de API no console do Cloud. Para mais informações, acesse Práticas recomendadas de segurança da API.

DeletedApiProjectMapError Erro

Verifique o projeto para o qual você gerou a chave incluída no carregador da API JavaScript, porque ele pode ter sido excluído do console do Cloud. É possível criar um novo projeto e gerar outra chave no console.

Para isso, clique no botão abaixo.
Saiba como

ClientBillingNotEnabledMapError Erro

Você não ativou o faturamento no projeto. Faça a ativação no projeto do Google Cloud associado a esse ID do cliente aqui.

BillingNotEnabledMapError Erro

O erro está ocorrendo porque você não ativou o faturamento no projeto. Faça a ativação no projeto do Google Cloud aqui.

Saiba mais

ExpiredKeyMapError Erro

A chave incluída no elemento de script que carrega a API está vencida ou não foi reconhecida pelo sistema. Se você criar e tentar usar uma chave de API antes de ela ser reconhecida pelo sistema, poderá receber esse erro. Aguarde alguns minutos e tente novamente. Talvez seja necessário gerar uma nova chave no console do Cloud.

Para conseguir uma, clique no botão abaixo.
Começar

InvalidClientIdMapError Erro

O ID do cliente incluído no elemento de script que carrega a API é inválido ou está vencido. Verifique se você está usando o ID corretamente. Ele deve ter o prefixo "gme-". Se o erro ocorrer mesmo que você use o ID de cliente correto, talvez ele esteja vencido. Entre em contato com o gerente de contas do Google.

Se você não tiver uma licença do Plano Premium ou das APIs Maps for Work, use um parâmetro key, em vez de client , com a chave de API.

Consulte o guia sobre autenticação do Plano Premium.

InvalidKeyMapError Erro

A chave incluída no elemento de script que carrega a API não foi encontrada. Verifique se está usando uma chave de API correta. É possível gerar outra no console do Cloud.

Para conseguir uma, clique no botão abaixo.
Começar

MalformedCredentialsMapError Erro

Seu aplicativo usa um esquema de URI incompatível. Verifique se o formato de URI usado é válido, conforme definido na RFC 3986.

MissingKeyMapError Erro

O elemento do script que carrega a API não tem o parâmetro de autenticação necessário.

Em APIs Maps JavaScript padrão, use um parâmetro key com uma chave de API válida. Para mais informações, consulte Começar a usar a Plataforma Google Maps.

Se você for cliente do Plano Premium, use um parâmetro client com o ID do cliente ou key com uma chave de API válida. Para mais informações, consulte o guia sobre chaves de API e IDs de cliente.

Se você NÃO for o proprietário do site, não poderá fazer nada para corrigir esse erro. Se possível, informe o proprietário.

ProjectDeniedMapError Erro

A solicitação não foi concluída. Mais detalhes sobre o erro estão disponíveis no console do Cloud.

Acesse Console do Cloud.

RefererDeniedMapError Erro

Após várias notificações por e-mail, seu aplicativo foi bloqueado por estar em desacordo com os Termos de Serviço da Plataforma Google Maps. Para contestar o bloqueio e pedir uma revisão da implementação, preencha este formulário. Você vai receber uma resposta por e-mail dentro de alguns dias úteis.

RefererNotAllowedMapError Erro

O URL que está carregando a API Maps JavaScript não está na lista de referenciadores permitidos. Verifique as configurações de referenciador da chave de API no console do Cloud.

Consulte a Referência da API Maps JavaScript e acesse Gerar uma chave de API.

OverQuotaMapError Erro

O número de solicitações excedeu o limite de uso da API Maps JavaScript. As solicitações do app vão voltar a funcionar quando a próxima cota diária for iniciada.

Se você NÃO for o proprietário do site, não poderá fazer nada para corrigir esse erro. Se possível, informe o proprietário.

Para mais detalhes, consulte o guia sobre limites de uso. O documento também explica como aumentar os limites.

ApiProjectMapError Erro

Não foi possível resolver a chave de API fornecida ou o projeto a que ela está associada. Esse erro pode ser temporário. Se a mensagem persistir, talvez seja necessário gerar outra chave ou criar um novo projeto.

Para mais informações, consulte Começar a usar a Plataforma Google Maps.

ClientIdLooksLikeCryptoKey Aviso

Talvez você tenha informado uma chave criptográfica no parâmetro client. Se você tiver uma licença do Plano Premium ou das APIs Maps for Work, especifique o ID do cliente como o parâmetro client. Não é necessário usar sua chave criptográfica para a API Maps JavaScript.

Consulte o guia sobre IDs de cliente para o Plano Premium e a API Maps for Work.

ClientIdLooksLikeKey Aviso

Talvez você tenha informado uma chave de API no parâmetro client. Se você tiver uma licença do Plano Premium ou das APIs Maps for Work, especifique o ID do cliente como o parâmetro client. No Plano Premium da Plataforma Google Maps, use um parâmetro client ou key. Se você não tiver nenhuma licença, use um parâmetro key em vez de client .

Consulte o guia sobre autenticação do Plano Premium.

InvalidChannel Aviso

O parâmetro channel informado talvez seja inválido. O canal precisa ser uma string alfanumérica ASCII, que pode incluir ponto (.), sublinhado (_) e hífen (-). Verifique se o parâmetro channel especificado é válido.

Consulte Relatórios | Plano Premium da Plataforma Google Maps.

InvalidClientId Aviso

Parece que o parâmetro client não contém um ID de cliente correto. Ele deve começar com "gme-".

Consulte o guia sobre autenticação do Plano Premium.

InvalidKey Aviso

A chave de API incluída no elemento de script que carrega a API não está correta. Verifique se está usando uma chave de API correta. É possível gerar outra no console do Cloud.

Para conseguir uma, clique no botão abaixo.
Começar

InvalidVersion Aviso

Talvez você tenha informado um número de versão incorreto no elemento de script. Verifique se ele está certo.

Consulte Controle de versões | API Google Maps JavaScript.

KeyLooksLikeClientId Aviso Talvez você tenha informado um ID do cliente como parâmetro key. Se você tiver uma licença do Plano Premium ou das APIs Maps for Work, especifique o ID de cliente como um parâmetro client em vez de key. No Plano Premium da Plataforma Google Maps, use um parâmetro client ou key. Se você não tiver nenhuma licença, use um parâmetro key em vez de client .

Consulte o guia sobre autenticação do Plano Premium.

KeyLooksLikeCryptoKey Aviso

Talvez você tenha informado uma chave criptográfica ou secreta de assinatura como parâmetro key. Se você tiver uma licença do Plano Premium ou das APIs Maps for Work, especifique o ID do cliente como parâmetro client e remova o parâmetro key do elemento de script. A chave criptográfica não é obrigatória para a API Maps JavaScript. No Plano Premium da Plataforma Google Maps, use um parâmetro client ou key. Se você não tiver nenhuma licença, gere uma chave de API no console do Cloud.

Consulte o guia sobre Especificar um ID do cliente ao carregar a API.

KeyLooksLikeProjectNumber Aviso

Talvez você tenha informado um número de projeto como parâmetro key. Verifique se está usando uma chave de API correta. É possível gerar outra no console do Cloud.

Saiba como fazer isso.

NoApiKeys Aviso

O elemento do script que carrega a API não tem uma chave. Inclua uma chave de API válida como parâmetro key. É possível gerar outra no console do Cloud.

Para isso, clique no botão abaixo para começar.
Começar

Se estiver carregando a API Maps JavaScript do caminho descontinuado da v2, você vai receber o aviso NoApiKeys mesmo que tenha especificado o parâmetro key. Consulte o Guia de upgrade da v2 para a v3 e migre seu aplicativo para a API Maps JavaScript v3.

RetiredVersion Aviso

Talvez você tenha informado uma versão desativada no elemento de script. Atualize o aplicativo para usar uma das versões disponíveis.

Consulte Controle de versões | API Google Maps JavaScript.

SensorNotRequired Aviso

O parâmetro sensor não é mais obrigatório para a API Maps JavaScript. Ele não impede que a API funcione corretamente, mas recomendamos que você remova sensor do elemento de script.

SignatureNotRequired Aviso

O parâmetro signature não é obrigatório para a API Maps JavaScript. Ele não impede que a API funcione corretamente, mas pode resultar em riscos de segurança. Remova o parâmetro do elemento de script.

SignedInNotSupported Aviso

O parâmetro signed_in foi descontinuado e não é compatível com a versão da API Maps JavaScript que você está usando. Ele não impede que a API funcione, mas pode mudar o comportamento do seu aplicativo, caso você use recursos com login.

UrlAuthenticationCommonError Erro

Ocorreu um erro que não se encaixa nas outras categorias desta página. Ele pode ter sido causado por um problema temporário. Aguarde um pouco e tente enviar a solicitação novamente. Se isso não resolver o problema, verifique no Guia para desenvolvedores se a solicitação está no formato adequado.

Verificar erros no navegador

A API Maps JavaScript grava mensagens de erro no window.console. Esta seção explica como verificar o resultado do window.console no Google Chrome. Se você estiver usando outro navegador, consulte a documentação para desenvolvedores relacionada. Esta é uma lista de ferramentas para verificar o resultado do window.console em alguns outros navegadores.

No Chrome, use o Console JavaScript para verificar o resultado do window.console, de acordo com estas orientações.

  1. Para abrir as Ferramentas para desenvolvedores, selecione o ícone de menu > Mais ferramentas > Ferramentas para desenvolvedores.
  2. Para abrir o Console JavaScript, pressione ESC no teclado. Essa tecla abre e fecha o Console JavaScript. Pressione ESC para abrir o console novamente, caso tenha fechado.

Os erros ou avisos que ocorrem durante o carregamento da API Maps JavaScript são mostrados como uma ou mais linhas no console. Este é o formato de uma mensagem de erro ou aviso:

Google Maps API error: [ERROR CODE] [Link to API document]
ou
Google Maps API warning: [ERROR CODE] [Link to API document]

Consulte a tabela de códigos de erro acima para encontrar o código da mensagem. O documento da API vinculado à mensagem também inclui detalhes da mensagem de erro.

Observação: é possível detectar erros de autenticação de maneira programática.

Lidar com navegadores incompatíveis

Use uma versão de navegador compatível com a API Maps JavaScript.

Se você estiver desenvolvendo um aplicativo nativo do Windows executado em um WebView, verifique se está usando o WebView2 com base no Edge. As versões anteriores do WebView com base no Internet Explorer não são mais compatíveis.

Se o código ainda não funcionar

Para que seu código de mapas funcione bem, Brendan Kenny e Mano Marks mostram neste vídeo alguns erros comuns e a correção deles.

  • Procure erros de digitação. A linguagem JavaScript diferencia maiúsculas de minúsculas.
  • Verifique os elementos básicos. Alguns dos problemas mais comuns ocorrem na criação inicial do mapa. Por exemplo:
    • Confirme se você especificou as propriedades zoom e center nas opções do mapa.
    • Verifique se declarou um elemento "div" que vai ser usado para mostrar o mapa na tela.
    • Confira se esse elemento tem uma altura. Por padrão, os elementos "div" são criados com uma altura de zero, o que os torna invisíveis.
    Consulte uma implementação de referência nos nossos exemplos.
  • Para identificar problemas, use um Depurador de JavaScript, como o disponível nas Ferramentas para desenvolvedores do Chrome. Comece procurando erros no Console JavaScript.
  • Faça perguntas no Stack Overflow. Confira na página Suporte orientações para postar boas perguntas.