Errores

Cuando una petición falla, la API responde con el estado HTTP adecuado y un cuerpo application/problem+json según el RFC 9457. Los errores no se cachean (Cache-Control: no-store) y llevan la cabecera X-Request-Id.

Formato

Ejemplo ilustrativo

{
  "type": "https://docs.preciosgasolina.es/conceptos/errores/#province-not-found",
  "title": "No encontrado",
  "status": 404,
  "detail": "No existe la provincia 99.",
  "code": "PROVINCE_NOT_FOUND",
  "request_id": "e74dbaec2b574590",
  "instance": "/v1/prices"
}

Campo	Significado
type	URL de la explicación del error en esta página (# + el código en minúsculas y con guiones).
title	Resumen legible del tipo de error.
status	El mismo estado HTTP de la respuesta.
detail	Explicación concreta de este caso (qué parámetro, qué valor).
code	Código estable del error. Es el campo que debe comprobar tu código.
request_id	Identificador de la petición (igual que la cabecera X-Request-Id). Inclúyelo si nos escribes.
instance	Ruta de la petición, cuando se conoce.

Comprueba el campo code, no el texto

title y detail son textos en español que pueden cambiar. code y status son estables dentro de la versión v1.

Solo 429 y 503 llevan Retry-After: son los únicos errores que se resuelven esperando. El resto se arreglan cambiando la petición.

Códigos

code	Estado	Cuándo
INVALID_PARAMETER	400	Parámetro desconocido, repetido, mal escrito o fuera de rango.
INVALID_JSON	400	El cuerpo de un POST no es JSON válido.
*_NOT_FOUND	404	La gasolinera, el territorio, la marca… no existe.
ENDPOINT_NOT_FOUND	404	La ruta no existe.
METHOD_NOT_ALLOWED	405	Método HTTP no admitido.
PAYLOAD_TOO_LARGE	413	Cuerpo de más de 32 KB.
URI_TOO_LONG	414	URL de más de 2.048 caracteres.
UNSUPPORTED_MEDIA_TYPE	415	POST sin Content-Type: application/json.
RATE_LIMITED	429	Has superado un límite por IP.
INTERNAL_ERROR	500	Error inesperado.
ENDPOINT_DISABLED	503	Endpoint desactivado temporalmente.
TEMPORARILY_UNAVAILABLE	503	Los datos no están disponibles en este momento.

INVALID_PARAMETER (400)

Un parámetro no es válido. detail dice cuál y por qué. Causas habituales:

• Un parámetro que el endpoint no admite (parámetros no admitidos: …): la API es estricta y no ignora parámetros desconocidos.
• Un parámetro repetido (?fuel=diesel&fuel=lpg).
• Un valor que no está en la lista (fuel=petrol) o fuera de rango (limit=500, radius_km=80, coordenadas fuera de España).
• Una combinación incompleta: lat sin lng, level=province sin code, municipios sin parent en /v1/territories, una ruta propia de más de 1.500 km, el informe de un mes que aún no ha terminado.

Qué hacer: corrige la petición; no reintentes.

INVALID_JSON (400)

El cuerpo de POST /v1/route/fuel no se puede leer como JSON. Comprueba que envías un JSON válido (por ejemplo, con JSON.stringify).

Recursos no encontrados (404)

Lo que pides no existe. El prefijo dice qué:

• STATION_NOT_FOUND: la gasolinera no existe o ya no vende al público.
• COMMUNITY_NOT_FOUND: no existe esa comunidad autónoma (código INE o slug).
• PROVINCE_NOT_FOUND: no existe esa provincia.
• MUNICIPALITY_NOT_FOUND: no existe ese municipio. Usa el id de /v1/search o /v1/territories, no el código INE.
• BRAND_NOT_FOUND: no existe esa marca (lista en /v1/brands).
• PRODUCT_NOT_FOUND: producto desconocido.
• ROAD_NOT_FOUND: no hay datos de esa carretera (lista en /v1/roads).
• REPORT_NOT_FOUND: no hay datos de ese mes.
• GUIDE_NOT_FOUND, ARTICLE_NOT_FOUND y ROUTE_NOT_FOUND: no existe esa guía, artículo del blog o ruta (busca en /v1/content o /v1/routes).

Qué hacer: comprueba el identificador con el endpoint de búsqueda o de lista correspondiente.

ENDPOINT_NOT_FOUND (404)

La ruta no existe. Revisa la referencia: todas las rutas empiezan por /v1/ y terminan sin extensión.

METHOD_NOT_ALLOWED (405)

La API es de solo lectura: admite GET, HEAD y OPTIONS, y POST solo en /v1/route/fuel. La respuesta lleva la cabecera Allow.

PAYLOAD_TOO_LARGE (413)

El cuerpo de POST /v1/route/fuel pasa de 32 KB. Envía menos puntos (como mucho 200). En el servidor MCP, un mensaje de más de 64 KB se rechaza con 413 y un error JSON-RPC.

URI_TOO_LONG (414)

La URL pasa de 2.048 caracteres. Si necesitas enviar muchos puntos, usa POST /v1/route/fuel.

UNSUPPORTED_MEDIA_TYPE (415)

Un POST sin Content-Type: application/json. Añade la cabecera.

RATE_LIMITED (429)

Has superado un límite por IP: 120 peticiones por minuto (o 20 cada 10 segundos) o 30 consultas pesadas por minuto. La respuesta lleva Retry-After (segundos) y RateLimit-Policy.

Qué hacer: espera lo que indique Retry-After y cachea las respuestas hasta meta.next_update. Ver Límites de uso.

INTERNAL_ERROR (500)

Error inesperado de la API. Puedes reintentar una vez pasados unos segundos; si se repite, escríbenos a hola@preciosgasolina.es con el request_id.

ENDPOINT_DISABLED (503)

El endpoint (o toda la API) está desactivado temporalmente, por ejemplo por mantenimiento. Lleva Retry-After: 3600.

TEMPORARILY_UNAVAILABLE (503)

La fuente de datos no responde, se ha alcanzado el presupuesto mensual de la API o no se pudo calcular la respuesta, y no hay una copia anterior que servir. Lleva Retry-After (normalmente 60 segundos).

Qué hacer: espera y reintenta; mientras tanto, muestra los últimos datos que tengas con su fecha. Ver Frescura de los datos.

Errores del servidor MCP

El servidor MCP usa errores JSON-RPC para los problemas de transporte (429 con Retry-After, mensaje de más de 64 KB, JSON no válido, lotes no admitidos, método GET) y, dentro de una llamada a herramienta, un resultado con isError: true cuyo texto empieza por el mismo code de esta página (por ejemplo, STATION_NOT_FOUND: No existe la gasolinera …).