# Límites de uso > Versión Markdown de https://docs.preciosgasolina.es/conceptos/limites/ · Actualizado: 2026-10-07 · Índice para LLM: https://docs.preciosgasolina.es/llms.txt Límites por IP de la API REST (120/min, 20 cada 10 s, 30/min pesadas) y del MCP (60 mensajes y 30 herramientas/min), topes, 429 y Retry-After. 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 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 ```json { "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](https://docs.preciosgasolina.es/guias/integrar-en-tu-web/#un-cliente-completo). ## 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](https://preciosgasolina.es/datos/) (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 contando qué haces. Los límites pueden cambiar con el uso real; los cambios se anotan en el [registro de cambios](https://docs.preciosgasolina.es/changelog/).