API de Boletín Claro · Errores

BC-1001 … BC-5002Códigos de error de la API

Todos los errores de la API siguen el RFC 9457, viajan como application/problem+json y llevan un código estable que identifica exactamente uno de los 16 casos de esta lista.

{
  "type": "https://boletinclaro.es/v1/errores/BC-1001",
  "codigo": "BC-1001",
  "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 codigo, o el type que lo contiene. Es lo estable: podemos reescribir el title y el detail, pero el código no cambia. Y cada type es una URL que se abre en el navegador y explica ese error concreto. Esta lista responde también en JSON con Accept: application/json.

El primer dígito dice de quién es el problema: BC-1xxx la petición está mal formada · BC-2xxx la clave o el plan · BC-3xxx no hay nada ahí · BC-4xxx vas demasiado rápido · BC-5xxx se ha roto de nuestro lado.

Los errores reintentables 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.

Código	HTTP	Qué ha pasado	Reintentar
BC-1001	400	Consulta no válida	No
BC-1002	400	Parámetro no válido	No
BC-1003	405	Método no permitido	No
BC-2001	401	Clave de API no válida	No
BC-2002	403	Tu plan no incluye la API	No
BC-3001	404	No encontrado	No
BC-3002	404	Ruta no encontrada	No
BC-4001	429	Demasiadas solicitudes	Sí
BC-4002	429	Límite de peticiones superado	Sí
BC-4003	429	Cuota mensual agotada	No
BC-4004	429	Límite mensual de perfiles alcanzado	Sí
BC-4005	429	Límite diario de créditos alcanzado	Sí
BC-4006	429	Límite mensual por usuario alcanzado	Sí
BC-4007	429	Máximo mensual de consultas de empresa y fichas alcanzado	Sí
BC-5001	500	Error interno	Sí
BC-5002	503	Servicio no disponible temporalmente	Sí

Cada código lleva a su propia página, con las causas concretas, cómo se arregla y la respuesta exacta que recibes.