Límites de uso

La API y el servidor MCP son gratuitos y no piden clave, así que se protegen con límites por IP, topes en los parámetros y un presupuesto mensual. Con un uso normal (y con caché hasta meta.next_update) no deberías llegar a ellos. La web preciosgasolina.es tiene siempre prioridad: si hay presión, la API se degrada sola.

Límites por IP

Qué	Límite
API REST	120 peticiones por minuto y 20 cada 10 segundos
Consultas pesadas de la API REST	30 por minuto (cuentan también en el límite general)
Servidor MCP: mensajes	60 por minuto
Servidor MCP: llamadas a herramientas (tools/call)	30 por minuto (de esos 60 mensajes)

Son consultas pesadas las que hacen cálculos geográficos o leen mucho histórico:

• GET /v1/stations/nearby (gasolineras cerca de unas coordenadas)
• GET /v1/stations/{id}/history (histórico de una gasolinera)
• GET /v1/routes/{slug} (ruta del catálogo con sus gasolineras)
• POST /v1/route/fuel (dónde repostar en tu ruta)

Las peticiones a rutas que no existen también cuentan. Las direcciones IPv6 se agrupan por su prefijo /64. La IP solo se usa para contar: no se guarda. Los contadores son aproximados y por centro de datos, así que el corte puede no ser exacto al segundo.

Qué pasa al superarlos

La API responde 429 Too Many Requests con el código RATE_LIMITED, la cabecera Retry-After: 60 y RateLimit-Policy con el límite aplicado:

Ejemplo ilustrativo

HTTP/2 429
content-type: application/problem+json; charset=utf-8
retry-after: 60
ratelimit-policy: "rest";q=120;w=60, "heavy";q=30;w=60

Ejemplo ilustrativo

{
  "type": "https://docs.preciosgasolina.es/conceptos/errores/#rate-limited",
  "title": "Demasiadas peticiones",
  "status": 429,
  "detail": "Has superado el límite de 30 consultas pesadas por minuto. Espera un minuto.",
  "code": "RATE_LIMITED",
  "request_id": "…",
  "instance": "/v1/stations/nearby"
}

Espera los segundos de Retry-After antes de reintentar; reintentar antes solo alarga el bloqueo. En el servidor MCP, el 429 lleva un error JSON-RPC («Demasiados mensajes» o «Demasiadas llamadas a herramientas») y también Retry-After: 60. Código de ejemplo con reintentos en Integrar en tu web.

Topes de parámetros y tamaños

Parámetro o tamaño	Tope
limit (resultados por petición)	1–50; por defecto 10 (en /v1/search, 1–20 y por defecto 8; en /v1/routes, por defecto 20; en /v1/brands, por defecto 50)
radius_km (radio)	hasta 50 km; por defecto 5
days (histórico diario)	1–90; por defecto 30
points (ruta propia)	de 2 a 200 puntos y 1500 km como mucho
corridor_km (distancia a la ruta)	hasta 10 km; por defecto 3
q / query (texto de búsqueda)	2–100 caracteres
URL	2048 caracteres (414 si es más larga)
Cuerpo de POST /v1/route/fuel	32 KB (413 si es mayor)
Mensaje MCP	64 KB
Resultado de una herramienta MCP	unos 20 KB: las listas se recortan a 10 elementos (truncated: true)

Un valor fuera de estos rangos devuelve 400 (INVALID_PARAMETER) con el motivo.

Presupuesto mensual y protección del servicio

Además de los límites por IP, la API tiene un presupuesto global de 1.500.000 peticiones al mes (para todos los usuarios a la vez) y un disyuntor que deja de consultar la base de datos si esta falla varias veces seguidas. En los dos casos la API no se cae, se degrada:

1. Sirve lo que ya tiene calculado en caché (respuesta normal).
2. Si no lo tiene, sirve la última copia buena de esa respuesta con meta.stale: true.
3. Si tampoco hay copia, responde 503 con TEMPORARILY_UNAVAILABLE y Retry-After.

Un endpoint o una herramienta pueden desactivarse temporalmente (por ejemplo, por mantenimiento): el endpoint responde 503 con ENDPOINT_DISABLED y Retry-After: 3600, y la herramienta devuelve isError: true con «Herramienta desactivada temporalmente».

Si necesitas más

Consejo

• Cachea hasta meta.next_update: los datos solo cambian dos veces al día.
• Para todas las gasolineras o todos los territorios, descarga los datos abiertos (CSV y JSON, misma licencia) en lugar de recorrer la API.
• Si tu caso de uso necesita límites más altos, escríbenos a hola@preciosgasolina.es contando qué haces.

Los límites pueden cambiar con el uso real; los cambios se anotan en el registro de cambios.