Anúncio:em breve, a Plataforma Google Maps vai ter um novo estilo de mapa de base. Essa atualização inclui uma nova paleta de cores padrão, pinos modernizados e melhorias nas experiências de mapa e na usabilidade. Todos os estilos de mapa serão atualizados automaticamente em março de 2025. Para mais informações sobre a disponibilidade e como ativar logo, consulte Novo estilo de mapa para a Plataforma Google Maps.

Esta página foi traduzida pela API Cloud Translation.

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.

Você está usando uma chave de API?

Não tenho certeza. Como verificar se estou usando uma chave de API?

A chave de API é transmitida como o parâmetro key no URL usado para carregar a API Maps JavaScript. Confira algumas opções para verificar se você está usando uma chave de API:

Use a extensão Google Maps Platform API Checker do Chrome. Ela permite que você determine se o seu site está implementando as APIs licenciadas do Maps de forma correta.
Se você estiver usando uma biblioteca ou um plug-in para carregar a API Maps JavaScript, verifique as configurações dessa biblioteca e procure uma opção de chave de API.
Verifique os erros no navegador. Se as mensagens a seguir forem exibidas, significa que você não está usando a chave de API corretamente:

Aviso da API Google Maps JavaScript: NoApiKeys
Erro da API Google Maps JavaScript: MissingKeyMapError

Para desenvolvedores Web:

Se você tiver acesso ao código-fonte do app, procure a tag <script>, que é usada para carregar a API Maps JavaScript. Ao carregar essa API, substitua YOUR_API_KEY no código abaixo pela sua chave de API.
```
  <script async defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
  </script>
```
Verifique o tráfego de rede gerado pelo seu site no navegador. No Google Chrome, isso pode ser visto na guia Rede do DevTools. Aqui, você verá as solicitações de rede feitas pelo seu site. As solicitações feitas usando a API Maps JavaScript estarão no caminho maps/api/js. Aqui, você pode confirmar se as solicitações estão usando o parâmetro key. Pode ser útil filtrar o tráfego de rede por maps/api/js ao visualizar a guia Rede.

Não estou usando uma chave de API.

Para conseguir uma, clique no botão abaixo. Se a configuração guiada não aparecer, siga as instruções completas em Começar a usar a Plataforma Google Maps.
Como começar

Estou usando uma chave de API.

Ótimo. Vamos verificar se há uma conta de faturamento vinculada ao seu projeto.

Há uma conta de faturamento vinculada ao projeto?

Não tenho certeza. Como verificar se há uma conta de faturamento vinculada ao meu projeto?

Acesse a página "Faturamento" no console do Google Cloud e selecione o projeto em que a chave de API foi criada. Para confirmar se a chave está associada ao projeto, siga estas etapas:

Vá para a seção Credenciais na barra lateral esquerda, em Plataforma Google Maps > Credenciais.
Verifique se a chave de API usada atualmente no seu site está listada. Se esse não for o caso, mude para outro projeto e verifique as credenciais.
Se não for possível localizar o projeto da sua chave de API, é possível que você tenha perdido o acesso a ele. Peça ajuda na sua organização. Se não for possível localizar o projeto original, faça o seguinte:
1. Crie um novo projeto. Selecione Novo projeto na lista de projetos ou escolha Criar projeto na página do Resource Manager.
2. Crie outra chave de API. Isso pode ser feito na página Credenciais. Clique em Criar credenciais e selecione Chave de API.

Após localizar o projeto no console do Cloud, verifique se há uma conta de faturamento vinculada. Para fazer isso, abra a seção Faturamento no menu à esquerda.

Não há uma conta de faturamento vinculada ao meu projeto.

Acesse a página Ativar faturamento no console do Cloud e adicione uma conta de faturamento ao seu projeto. Para mais informações, consulte o artigo Começar a usar a Plataforma Google Maps.

Há uma conta de faturamento vinculada ao meu projeto.

Ótimo. Vamos verificar se o método de faturamento fornecido é válido.

O método de faturamento fornecido não é mais válido (por exemplo, um cartão de crédito expirado)?

É possível adicionar, remover ou atualizar uma forma de pagamento no console do Cloud.

Você excedeu o limite diário que determinou para a API?

Se você definiu um limite diário em qualquer uma das suas APIs (o que é comum para evitar aumentos inesperados), aumente seu limite diário para resolver esse problema.

Para conferir seus limites diários, acesse o painel de APIs e serviços no console do Cloud. Depois, siga estas etapas:

Selecione um projeto, se solicitado.
Selecione uma API na lista e clique na guia Cotas.

Sua chave de API tem uma restrição quanto a endereços IP?

As chaves de API com uma restrição a endereços IP só podem ser usadas com serviços da Web destinados ao uso do servidor (como a API Geocoding e outras APIs de serviços da Web). A maioria desses serviços da Web tem funções equivalentes na API Maps JavaScript (por exemplo, consulte o Serviço de geocodificação). Para usar os serviços do lado do cliente da API Maps JavaScript, crie uma chave de API que pode ser protegida com uma restrição a referenciadores HTTP (consulte Receber, adicionar e restringir uma chave de API).

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

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.

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
`InvalidAppCheckTokenMapError`	Erro	O token do App Check fornecido é inválido ou expirou. Esse erro só pode ocorrer se a verificação do App Check estiver em uso. Consulte o guia sobre a verificação do App Check.
`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.

Console da Web do Firefox.
Depuração remota para Android.
Web Inspector para iOS.

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

Para abrir as Ferramentas para desenvolvedores, selecione o ícone de menu > Mais ferramentas > Ferramentas para desenvolvedores.
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.