Referência

Erros

Quando uma chamada falha, a resposta diz o que deu errado e o que fazer. Aqui estão todos os códigos de erro e como tratar cada um.

Como é um erro

Quando uma chamada falha, a resposta traz um status HTTP e um objeto error em vez de data. Este é o erro que volta quando você inicia uma coleta depois que os créditos do dia acabaram:

HTTP/2 429
retry-after: 3600
x-request-id: 7c1e0b54-9a2f-4d3e-8f61-2b5a9c0d4e17

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "You reached your daily limit of 250 credits. Retry after midnight UTC. Buying credits does not raise this limit.",
    "messageKey": "serverErrors.quotaDay",
    "params": { "limit": 250 },
    "details": {
      "scope": "day",
      "limit": 250,
      "resetAt": "2026-09-25T00:00:00.000Z",
      "retryAfterSecs": 3600
    }
  }
}

code: o que deu errado, como um dos códigos abaixo. Os códigos não mudam, mas as mensagens podem mudar. Por isso, o seu programa deve verificar code, não message.
message: o problema e o que fazer, em inglês. Registre no log ou mostre para o usuário.
messageKey e params: uma chave fixa e os valores que a completam, para um app mostrar a mensagem no idioma dele. A maioria dos erros traz os dois.
details: mais informações sobre o erro, quando há o que dizer. Numa requisição inválida, lista os campos com problema. Num limite, diz qual foi e quando ele zera.

O SDK lança os mesmos campos num GmapsError, com status, requestId e retryAfter a mais. No MCP, uma chamada de ferramenta que falha volta com isError: true e este objeto como texto.

Todos os códigos de erro

Cada código vem sempre com o mesmo status HTTP. A coluna Origem diz onde está o problema: na sua requisição, nos limites do seu plano, do nosso lado ou no Google Maps.

Código	Status	Origem	O que aconteceu	O que fazer
`VALIDATION_ERROR`	400	Você	Falta algo na requisição, ou algo está errado. Quando o problema é num campo, `details` lista cada campo com o caminho dele.	Corrija a requisição. Se for enviada do mesmo jeito, vai falhar de novo.
`UNAUTHORIZED`	401	Você	A chamada veio sem chave de API, ou fora do formato `Authorization: Bearer`.	Envie sua chave como `Authorization: Bearer gm_…`. Veja Autenticação.
`INVALID_TOKEN`	401	Você	A chave está errada, foi revogada ou expirou, ou é o token de login do console em vez de uma chave de API.	Use uma chave ativa, ou crie outra em Chaves de API.
`PLAN_GATE`	402	Seu plano	Seu plano não inclui esse recurso. `details.gate` diz qual é, e `details.upgradeTo`, o plano que inclui.	Troque de plano em Plano e tente de novo. Esperar não resolve.
`AUP_REQUIRED`	403	Você	Para receber e-mails, você precisa aceitar a versão atual da política de uso aceitável, e sua conta ainda não aceitou. `details.version` é a versão que falta aceitar.	Leia a política, aceite no console, em Conta, e tente de novo.
`FORBIDDEN`	403	Você	Sua conta não pode fazer isso: está suspensa, ou você pediu para excluí-la.	A mensagem diz qual é o caso. Para desistir da exclusão, entre no console e cancele. Nos outros casos, escreva para o suporte.
`NOT_FOUND`	404	Você	Essa rota ou esse id não existe, ou pertence a outra conta.	Confira o método, a URL e o id.
`PLACE_NOT_FOUND`	404	Você	Ainda não salvamos esse lugar, ou ele foi removido depois de um pedido de remoção.	Busque na região dele para coletá-lo e consulte de novo. Um lugar removido não volta. Veja Lugares.
`COLLECTION_NOT_FOUND`	404	Você	Sua conta não tem nenhuma coleta com esse id.	Confira o id. `GET /v1/collections` lista as suas.
`EXPORT_NOT_FOUND`	404	Você	O link da exportação tem mais de 24 horas, os lugares da coleta foram apagados, ou o link está errado.	Crie outra exportação. Se a coleta tiver mais de 30 dias, rode a coleta de novo antes.
`CONFLICT`	409	Você	A chamada não combina com a situação atual, como cancelar uma coleta que já terminou ou criar uma chave além do limite do plano.	A mensagem diz o que está impedindo. Resolva isso e tente de novo.
`PAYLOAD_TOO_LARGE`	413	Você	O corpo da requisição passou do tamanho que aceitamos. `params.limit` é o máximo, em bytes.	Envie um corpo menor.
`GEO_UNRESOLVED`	422	Você	Não achamos a cidade que você informou, ou há mais de uma cidade com esse nome. Pelo nome, só funcionam cidades brasileiras.	Inclua o estado, como `Curitiba, PR`, ou escolha uma em `details.candidates`. Fora do Brasil, envie `lat`, `lng` e `radiusM`, ou um `bbox`.
`UPSTREAM_BLOCKED`	422	Google Maps	Ainda não enviamos este código. Ele está reservado para quando o Google Maps recusar nossas buscas. Hoje, uma coleta cujas buscas falham termina com `ENGINE_UNAVAILABLE`.	Nada, por enquanto. Se quiser tratar mesmo assim, tente de novo mais tarde, com uma região menor.
`RATE_LIMIT_EXCEEDED`	429	Seu plano	Sua conta fez mais chamadas neste minuto do que o plano permite.	Espere os segundos indicados em `retry-after` e tente de novo. `details.limit` diz quantas chamadas o limite permite, e `details.window`, em que período: `minute`, ou `hour` no caso do formulário de remoção.
`QUOTA_EXCEEDED`	429	Seu plano	Os créditos do dia ou do mês acabaram, ou você já está com todas as coletas simultâneas que o plano permite. `details.scope` diz qual.	Depende de `details.scope`. Veja a próxima seção.
`INTERNAL_ERROR`	500	Nós	Algo deu errado do nosso lado.	Tente de novo. Se continuar falhando, escreva para o suporte com o `x-request-id`.
`ENGINE_UNAVAILABLE`	503	Nós	Não conseguimos rodar as buscas de uma coleta, então ela não encontrou nada e não cobrou nada. Isso aparece no `error` da coleta, não como uma chamada que falhou.	Comece a coleta de novo daqui a alguns minutos. As buscas continuam respondendo com os lugares que já salvamos.
`SERVICE_UNAVAILABLE`	503	Nós	Um serviço do qual dependemos, como o banco de dados, não respondeu.	Tente de novo em alguns segundos. Se continuar falhando, escreva para o suporte.
`BILLING_UNAVAILABLE`	503	Nós	Não conseguimos falar com o nosso provedor de pagamentos, ou os pagamentos ainda não estão configurados. Só a página Plano do console passa por isso, nunca a API.	Tente de novo mais tarde. Nada foi cobrado.

Recursos do plano e limites

Só o PLAN_GATE responde 402. Ele quer dizer que o seu plano não inclui o recurso, então esperar não muda a resposta. details.upgradeTo diz o plano mais barato que tem o recurso. Troque em Plano e tente de novo.

Estourar um limite responde 429, e esperar resolve. RATE_LIMIT_EXCEEDED quer dizer chamadas demais neste minuto. QUOTA_EXCEEDED é sobre créditos ou coletas, e details.scope diz qual:

month: os créditos do mês acabaram, incluindo os de pacote. details.resetAt é o dia 1º do mês que vem, à meia-noite UTC. Com um pacote de créditos, você continua na hora.
day: você chegou ao limite de hoje. details.resetAt é a próxima meia-noite UTC (21h em Brasília). Pacotes não aumentam esse limite.
concurrency: você já está com todas as coletas simultâneas que o plano permite. Tente de novo quando uma terminar. Aqui não há resetAt.

Em Limites estão todos os números de cada plano.

Quando tentar de novo

Quando a resposta traz o cabeçalho retry-after, espere esse número de segundos e mande a mesma chamada de novo. RATE_LIMIT_EXCEEDED sempre traz, e QUOTA_EXCEEDED também, quando é day ou month. O mesmo número está em details.retryAfterSecs.
Qualquer outro 4xx: corrija primeiro o que a mensagem aponta. Se for enviada do mesmo jeito, a chamada costuma receber a mesma resposta.
Um 5xx é problema nosso. Tente de novo depois de alguns segundos e espere um pouco mais a cada falha. O SDK não tenta de novo sozinho.

Como pedir ajuda

Toda resposta, com erro ou não, traz o cabeçalho x-request-id. Ele aponta para aquela chamada nos nossos logs. Ao escrever para o suporte, mande esse id junto com o que você enviou e quando.

Você também pode mandar o seu próprio x-request-id, como o id que os seus logs já usam, para o mesmo id acompanhar a chamada dos seus logs até os nossos. Use até 64 letras, números, pontos, hifens e underscores, e nada mais. Caso contrário, geramos um novo.

Nunca mande sua chave de API. Não precisamos dela para achar a chamada.