Cuotas, crédito y límites

Cada clave recibe una cuota diaria gratuita. A partir de ahí, las solicitudes se descuentan del crédito prepago o las cubre un paquete Unlimited. Cada respuesta te indica en sus cabeceras cómo vas.

La cuota diaria

La cuota con clave es por clave, no por cuenta: tres claves suponen tres veces 2.500 solicitudes gratuitas. La cuota sin clave es por dirección, y las direcciones de la misma red la comparten. Una red y las claves que se usan desde ella comparten una sola cuota: las solicitudes sin clave reducen lo que obtiene ese día una clave usada desde la misma red, y viceversa, así que las 2.500 gratuitas no se pueden obtener dos veces desde un mismo lugar. El crédito es por cuenta y lo consume cualquier clave que supere su cuota. El día es el día natural UTC; X-Quota-Reset indica la hora Unix exacta del próximo reinicio.

Qué cuenta como solicitud

• Cada llamada correcta (200) a cualquier endpoint cuenta como una, haya encontrado algo o no.
• Cada elemento de una llamada masiva cuenta como una solicitud: cada dirección de un lote de IP, cada punto de una llamada de elevación o zona horaria con varios puntos, cada entrada en los endpoints de lotes de los hosts compatibles. Así es como los cuentan también los proveedores originales. Un lote mayor que lo que queda de la cuota se rechaza entero, antes de procesar nada, con el propio error de límite del proveedor, en lugar de responderse en parte. Cada host acepta tantos elementos por llamada como su proveedor original (100 para ip-api y MapQuest, 50 para ipstack, 512 para la elevación de Google, 1.000 para ipinfo, Mapbox y Geoapify, 1.024 para Bing y Open-Elevation, 10.000 para Geocodio y el lote asíncrono de TomTom; 100 en los endpoints nativos). Recuperar un resultado asíncrono almacenado no cuenta nada.
• Las llamadas rechazadas con 400, 401, 402, 403 o 404 no cuentan y no cuestan nada.
• Las llamadas que fallan con 500 o 503 no cuentan y no cuestan nada.
• Las teselas de mapa, el JSON de estilos y las cargas de bibliotecas de los reemplazos compatibles en JavaScript no cuentan.

Espacios de IP

Una clave funciona desde dos direcciones IP a la vez (tres para una clave Unlimited). Cada dirección mantiene su espacio durante 24 horas desde su primera solicitud y luego lo libera. Una solicitud desde otra dirección mientras todos los espacios están ocupados recibe 403 key_ip_limit con la hora a la que se libera el siguiente espacio. Los detalles y ejemplos están en la página de autenticación.

Ráfagas

Hoy no hay un límite fijo de solicitudes por segundo, con o sin clave. El tráfico que parezca un bucle descontrolado o un ataque puede ralentizarse, y te avisaremos si eso le ocurre a alguna de tus claves. Si tienes un trabajo grande, usa las formas por lotes (ips, locations) en lugar de miles de llamadas sueltas.

Cómo leer las cabeceras

x-quota-limit: 2500          # free per day for this key; -1 on an Unlimited key
x-quota-used: 2431           # counted today on this key, including this request
x-quota-free-remaining: 69   # free requests left today on this key
x-credits-remaining: 148200  # requests the account's credit still covers
x-key-ips-used: 1            # IP slots currently held on this key
x-key-ips-limit: 2           # slots on this key
x-quota-reset: 1789948800    # Unix time of the next 00:00 UTC
x-request-id: 2726386e38428697

Cómo gestionar 402 y 403

{ "status": "error", "error": { "code": "no_credits", "message": "The free allowance of 2500 requests for today is used and the account balance (€0.0000, 0 requests) does not cover this request. Add credit at https://www.mygeocode.com/dashboard or wait for the reset at 00:00 UTC." } }

No reintentes en bucle; la respuesta será la misma hasta que se añada crédito o se reinicie el día. Lee X-Quota-Reset y espera, da la operación por fallida e informa al usuario, o recarga. El panel te envía un correo cuando el crédito se está agotando.

{ "status": "error", "error": { "code": "key_ip_limit", "message": "This key is already in use from 2 IP addresses in the last 24 hours (limit 2). The next slot frees at 2026-09-21 23:06 UTC. Use another key or an additional Unlimited package for more addresses." } }

Significa que una máquina que no ocupa ninguno de los espacios actuales de la clave intentó usarla. Normalmente es un servidor nuevo o un redespliegue con una dirección nueva; dale a esa máquina su propia clave.

Cómo reducir las solicitudes

Puedes guardar los resultados en caché indefinidamente, así que hazlo. Las direcciones no se mueven; la misma geocodificación directa mañana da la misma respuesta. Los bloques de IP cambian despacio; un día es un tiempo de caché seguro. Las reglas de zona horaria de un punto cambian rara vez y el nombre IANA prácticamente nunca. Para el autocompletado, aplica un debounce a la entrada de unos 150 ms y deja de enviar en cuanto el usuario haya elegido una sugerencia.