Errores

Una llamada que falla responde con un código de estado HTTP y un objeto error en lugar de data. Este viene de empezar una recopilación cuando ya se acabaron los créditos de hoy:

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: qué salió mal, como uno de los códigos de abajo. Los códigos no cambian, pero los mensajes sí pueden cambiar, así que en tu programa revisa code, no message.
• message: el problema y qué hacer, en inglés. Guárdalo en tus logs o muéstraselo a una persona.
• messageKey y params: una clave fija y los valores que la completan, para que una app pueda mostrar el mensaje en su propio idioma. La mayoría de los errores los traen.
• details: más sobre este error, cuando hay algo más que decir. En una solicitud incorrecta, lista los campos que fallaron. En un límite, dice cuál y cuándo se reinicia.

El SDK lanza los mismos campos como un GmapsError, con status, requestId y retryAfter de más. Por MCP, una llamada a una herramienta que falla vuelve con isError: true y este objeto como texto.

Cada código viene siempre con el mismo estado HTTP. La columna Origen dice dónde está el problema: en tu solicitud, en los límites de tu plan, de nuestro lado o en Google Maps.

Solo PLAN_GATE responde 402. Significa que tu plan no incluye la función, así que esperar no cambia la respuesta. details.upgradeTo dice cuál es el plan más barato que la incluye. Cambia en Plan y vuelve a intentarlo.

Agotar un límite responde 429, y esperar lo resuelve. RATE_LIMIT_EXCEEDED significa demasiadas llamadas en este minuto. QUOTA_EXCEEDED trata de créditos o recopilaciones, y details.scope dice cuál:

• month: los créditos de este mes se acabaron, incluidos los de paquetes. details.resetAt es el día 1 del mes siguiente a medianoche UTC. Con un paquete de créditos puedes seguir de inmediato.
• day: llegaste al límite de hoy. details.resetAt es la próxima medianoche UTC. Un paquete no lo aumenta.
• concurrency: ya tienes en marcha todas las recopilaciones que permite tu plan. Vuelve a intentarlo cuando termine una. Aquí no hay resetAt.

En Límites están todos los números de cada plan.

• Cuando la respuesta trae un encabezado retry-after, espera esa cantidad de segundos y envía la misma llamada otra vez. RATE_LIMIT_EXCEEDED siempre lo trae, y QUOTA_EXCEEDED también cuando es day o month. El mismo número está en details.retryAfterSecs.
• Cualquier otro 4xx: corrige primero lo que señala el mensaje. Si la llamada se envía igual, casi siempre recibe la misma respuesta.
• Un 5xx es de nuestro lado. Vuelve a intentarlo después de unos segundos y espera un poco más tras cada falla. El SDK no reintenta por ti.

Cada respuesta, con error o sin él, trae un encabezado x-request-id. Señala esa llamada en nuestros logs. Cuando escribas a soporte, envíalo junto con lo que enviaste y cuándo.

También puedes enviar tu propio x-request-id, como el id que ya usan tus logs, para que un solo id siga la llamada desde tus logs hasta los nuestros. Usa hasta 64 letras, dígitos, puntos, guiones y guiones bajos, y nada más. Si no, generamos uno nuevo.

Nunca nos envíes tu clave de API. No la necesitamos para encontrar la llamada.