O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Mensagens de erro

Nesta página, descrevemos as mensagens de erro que a API Maps JavaScript pode retornar. A API Maps JavaScript 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 de erro, 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 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 a API Maps JavaScript, 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 obter uma chave de API, 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 posso 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 de erro, 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. Use as credenciais da chave de API ou do ID do cliente para resolver esse erro. Consulte o guia sobre chaves de API e IDs de cliente.
`UnauthorizedURLForClientIdMapError`	Esse URL não está autorizado a usar o ID do cliente do Google Maps informado.	O ID do cliente 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.

Use as credenciais da chave de API ou do ID do cliente para resolver esse erro. Consulte o guia sobre chaves de API e IDs de cliente.

UnauthorizedURLForClientIdMapError

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

O ID do cliente 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. Um erro indica um problema grave que ocorreu ao carregar a API Maps JavaScript. A API não foi carregada corretamente e não vai funcionar na página. Um aviso é uma mensagem complementar sobre o carregamento da API Maps JavaScript. O aviso descreve os possíveis motivos para um erro ou sugere possíveis problemas no código que carrega a API Maps JavaScript. 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. Talvez seja necessário ativar a API Maps JavaScript em "APIs", no console do Google Cloud. Para ativar a API Maps JavaScript no seu 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 de API 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	Seu projeto de API pode ter sido excluído do console do Cloud. Verifique o projeto em que você gerou a chave de API incluída no carregador da API JavaScript. É possível criar um novo projeto e gerar outra chave no console do Cloud. Para criar um novo projeto e obter uma chave de API para o projeto, 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 de API 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 de novo. Talvez seja necessário gerar uma nova chave de API no console do Cloud. Para obter uma chave de API, 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	Para aumentar a segurança e a confiabilidade da autenticação, os IDs de cliente da Plataforma Google Maps foram descontinuados em 26 de maio de 2025 e não poderão mais ser usados após 31 de maio de 2026. Em vez de usar um ID do cliente, use credenciais de chave de API para autenticar o tráfego de serviço da API Google Maps. Para mais informações, acesse o guia de migração do ID do cliente. Siga as etapas do guia para restaurar o ID do cliente temporariamente.
`InvalidKeyMapError`	Erro	A chave de API 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 uma nova chave de API no console do Cloud. Para obter uma chave de API, 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. Se você estiver usando a API Maps JavaScript, 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ê estiver usando um ID do cliente, 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 do 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 o 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 de uso.
`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 esta mensagem de erro persistir, talvez seja necessário gerar uma nova chave de API ou criar um novo projeto de API. 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`. Especifique seu 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.
`ClientIdLooksLikeKey`	Aviso	Talvez você tenha informado uma chave de API no parâmetro `client`. Especifique o ID do cliente como o parâmetro `client` ou use um parâmetro `key` com uma chave de API válida em vez de um parâmetro `client`. Consulte o guia sobre chaves de API e IDs de cliente.
`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 \| Plataforma Google Maps.
`InvalidClientId`	Aviso	Parece que o parâmetro `client` não contém um ID de cliente correto. Um ID do cliente deve começar com "gme-". Consulte o guia sobre chaves de API e IDs de cliente.
`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 uma nova chave de API no console do Cloud. Para obter uma chave de API, 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`. Especifique o ID do cliente como um parâmetro `client` em vez de `key` ou use um parâmetro `key` com uma chave de API válida. Consulte o guia sobre chaves de API e IDs de cliente.
`KeyLooksLikeCryptoKey`	Aviso	Talvez você tenha informado uma chave criptográfica ou secreta de assinatura como parâmetro `key`. 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. Como alternativa, você pode receber uma chave de API no console do Cloud e usar um parâmetro `key`. 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 uma nova chave de API no console do Cloud. Saiba como obter uma chave de API.
`NoApiKeys`	Aviso	O elemento do script que carrega a API não tem uma chave de API. Inclua uma chave de API válida como parâmetro `key`. É possível gerar uma nova chave de API no console do Cloud. Para obter uma chave de API, 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 do erro na mensagem de erro. 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 como corrigi-los.

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.