API de Boletín Claro · Errores
Errores de la API
Todos los errores de la API siguen el
RFC 9457 y viajan como
application/problem+json:
{
"type": "https://boletinclaro.es/v1/errores/consulta-invalida",
"title": "Consulta no válida",
"status": 400,
"detail": "El parámetro «consulta» debe tener entre 2 y 2000 caracteres."
}El campo que debes mirar en tu código es type. Es estable: podemos reescribir
el title y el detail, pero el identificador no cambia. Y es esta misma
página — cada type se puede abrir en el navegador. Con
Accept: application/json esta lista responde en JSON.
Los errores que se pueden reintentar traen la cabecera Retry-After con los
segundos que hay que esperar. Los dos 429 se despejan con un minuto de diferencia
uno y con un mes el otro, así que la cabecera no es un adorno.
400consulta-invalida
Consulta no válida
Qué significa
El parámetro «consulta» tiene menos de 2 caracteres, o falta. Por arriba no hay error: una consulta de más de 2.000 caracteres se recorta y la búsqueda sigue adelante.
¿Merece la pena reintentar? No
No. La petición es la que está mal; reintentarla tal cual da el mismo error. Manda una descripción de al menos dos caracteres.
400parametro-invalido
Parámetro no válido
Qué significa
Uno de los parámetros no vale: un «tipo» que no es subvenciones/licitaciones/ambos, un código de boletín que no existe, un CPV mal formado, un NIF que no lo parece o un «limite» fuera de 1 a 50. El detalle dice cuál.
¿Merece la pena reintentar? No
No. Corrige el parámetro que nombra el detalle y vuelve a llamar.
401clave-no-valida
Clave de API no válida
Qué significa
La clave que mandaste no existe o fue revocada. Ojo: sin clave la API responde igualmente, con el límite compartido por IP — este error solo aparece si mandas una, así que una clave mal copiada es peor que ninguna.
¿Merece la pena reintentar? No
No. Revisa la clave, o quita la cabecera «Authorization» para seguir de forma anónima. En Ajustes → API (https://boletinclaro.es/ajustes/api) puedes ver cuáles siguen vivas y crear otra; la clave en claro solo se enseña al crearla, así que si la has perdido, crea una nueva y revoca la vieja.
403sin-acceso-api
Tu plan no incluye la API
Qué significa
La clave es buena y el espacio de trabajo existe, pero su plan no incluye acceso programático.
¿Merece la pena reintentar? No
No. Cambia de plan o usa la API sin clave, con el límite compartido por IP.
404no-encontrado
No encontrado
Qué significa
La ruta existe y lo que pediste no. Hoy solo lo emite /v1/empresas/{nif}: no tenemos ningún registro de dinero público para ese NIF. No es un error de la petición.
¿Merece la pena reintentar? No
No de inmediato: el dato no está. Puede aparecer más adelante si la empresa recibe una subvención o gana un contrato, así que tiene sentido volver a consultarlo cada cierto tiempo, no en bucle.
404ruta-no-encontrada
Ruta no encontrada
Qué significa
Esa URL no existe en la versión 1 de la API. Casi siempre es una errata o un endpoint que imaginaste: la lista completa de rutas está en la referencia y en el documento OpenAPI.
¿Merece la pena reintentar? No
No. Corrige la URL.
429limite-por-ip
Demasiadas solicitudes
Qué significa
Has pasado el límite anónimo de 20 peticiones por minuto. Ese cubo va por IP y se COMPARTE con todo el que salga por la misma, así que puedes toparte con él sin haber hecho tú las peticiones.
¿Merece la pena reintentar? Sí
Sí, y pronto: la cabecera «Retry-After» trae los segundos que faltan, siempre menos de un minuto. Si te pasa a menudo, pide una clave: con clave tienes tu propio cubo y dejas de competir por el compartido.
429limite-por-minuto
Límite de peticiones superado
Qué significa
Has pasado el ritmo por minuto de tu clave. Este cubo es tuyo, no lo comparte nadie.
¿Merece la pena reintentar? Sí
Sí, y pronto: «Retry-After» trae los segundos que faltan, siempre menos de un minuto. Espera eso y sigue; no hace falta backoff exponencial.
429cuota-agotada
Cuota mensual agotada
Qué significa
Has consumido la cuota mensual de tu clave. Es el otro 429, y no se parece en nada al anterior: este no se despeja esperando un rato.
¿Merece la pena reintentar? No
No hasta el día 1 del mes que viene. «Retry-After» trae los segundos exactos que faltan, las cabeceras «X-RateLimit-*» la fecha en RFC 3339, y Ajustes → API el consumo del mes de cada clave. Reintentar antes de eso no puede funcionar: para el resto del mes trata la clave como agotada en vez de sondearla.
500error-interno
Error interno
Qué significa
Algo se ha roto de nuestro lado. Tu petición probablemente era correcta.
¿Merece la pena reintentar? Sí
Una vez, esperando unos segundos. Si se repite con la misma petición no es transitorio: escríbenos a hola@boletinclaro.es con la URL y te decimos qué pasa.
503servicio-no-disponible
Servicio no disponible temporalmente
Qué significa
Una pieza de la que dependemos no responde ahora mismo: el motor de búsqueda, BigQuery, la validación de claves o el resolutor de geografía. Ese último caso es deliberado — si no podemos resolver la «zona» que pides preferimos fallar a devolverte resultados de toda España como si hubieras filtrado.
¿Merece la pena reintentar? Sí
Sí. «Retry-After» trae una espera prudente; a partir de ahí, backoff exponencial. Si el que falla es el resolutor de geografía, repetir la búsqueda sin «zona» funciona ya.