Errores y límites
Errores y límites
El mismo formato en todos los fallos, y los códigos que puede dar hoy /v1/dev/*.
El formato de un error
Todo fallo contesta en JSON, con un código estable para el programa y un mensaje en castellano para quien lo lea:
{
"codigo": "clave_invalida",
"mensaje": "Esa clave de API no existe o ha sido revocada."
}Los códigos de hoy
cuerpo_de_validacionUn parámetro no tiene la forma que pide el endpoint (p. ej. una fecha que no es AAAA-MM-DD).
no_autenticadoFalta la cabecera Authorization con la clave de API.
clave_invalidaLa clave no existe, está mal escrita o ha sido revocada.
clave_ip_no_permitidaLa clave lleva una lista blanca de IPs/CIDR (Configuración › API) y la petición no viene de ninguna de ellas. La clave en sí es válida: lo que falla es desde dónde se usa.
no_encontradoLa empresa, la persona o el día pedido no están en lo que tenemos cargado del BORME.
—La ruta no existe todavía en tu entorno: la plataforma se abre por fases.
saldo_insuficienteSin saldo disponible para una consulta de pago (o, en el asistente, para reservar su peor caso). No se sirve ni se cobra. Qué hacer: recarga tu saldo; no reintentes.
coste_maximo_superadoEl peor caso del asistente supera tu `maxCosteCentimos`. No se llama al modelo ni se cobra. Qué hacer: sube el tope o acorta la pregunta.
—Un cálculo al que le falta un dato que lo decide, o con un régimen no verificado contra el BOE. No se cobra (una respuesta 4xx nunca se cobra). Qué hacer: añade el dato que pide la respuesta.
—No se entiende qué artículo se pide en la biblioteca. Qué hacer: escribe la cita como «ET 59» o «art. 59.3 ET».
adjunto_demasiado_grandeLos archivos adjuntos al asistente pasan de algún límite: tamaño por fichero o por petición, número de ficheros, páginas o páginas escaneadas (OCR). Los límites exactos están en la guía «Preguntar sobre un documento». No se lee nada ni se cobra. Qué hacer: manda menos, o divide el documento.
adjunto_tipo_no_admitidoUn archivo no es PDF, Word moderno (.docx), JPEG ni PNG. Se mira el contenido del fichero, no su nombre ni el Content-Type declarado. No se cobra. Qué hacer: convierte el .doc antiguo a .docx o PDF.
adjunto_ilegibleUn archivo adjunto está dañado, tiene contraseña, o no se le ha podido sacar texto (en blanco, foto ilegible). No se cobra. Qué hacer: prueba con otra foto, o con un PDF que lleve el texto dentro.
asistente_del_portal_falloEl modelo ha fallado a medias. No se cobra nada. Qué hacer: reintenta con espera exponencial.
asistente_del_portal_no_disponibleEl asistente no está disponible ahora (sin modelo o sin tarifa). No se cobra. Qué hacer: reintenta más tarde.
ocr_del_asistente_no_disponibleHacía falta leer páginas escaneadas o fotos (OCR) y la lectura no está disponible o ha tardado más de lo permitido. No se cobra. Qué hacer: manda un PDF que lleve el texto dentro, o menos páginas escaneadas.
asistente_del_portal_no_disponibleCon archivos adjuntos, ahora mismo no hay ningún proveedor de IA acreditado para tratar documentos de personas (encargo de tratamiento, residencia en la UE y sin conservar ni entrenar con los datos). No se envía nada ni se cobra. Qué hacer: reintenta más tarde, o pregunta sin archivos.
error_internoUn fallo nuestro. No se cobra. Qué hacer: reintenta alguna vez con espera exponencial y avísanos si persiste.
demasiadas_peticionesSe ha superado el límite de la clave. La cabecera Retry-After dice, en segundos, cuándo volver a intentarlo.
Límite de peticiones
Cada clave de API puede hacer 120 llamadas por minuto a /v1/dev/*, también en las APIs gratuitas (el mismo límite que usa, para las mismas consultas, la app móvil de Jurilia). Toda respuesta lleva tres cabeceras para seguir el consumo sin tener que provocar un 429:
X-RateLimit-LimitEl tope de la ventana actual: 120.
X-RateLimit-RemainingCuántas llamadas quedan en esta ventana de un minuto.
X-RateLimit-ResetCuándo se reinicia la ventana, como instante Unix (segundos).
Restricción por IP/CIDR
Es aparte del límite de peticiones, y opcional: una clave puede llevar una lista de IPs o redes (formato CIDR, IPv4 o IPv6). Vacía —lo normal— significa sin restricción; con la lista puesta, una llamada desde fuera de ella da 403, aunque la clave sea válida. Pendiente: el panel de desarrollador todavía no permite configurarla.
Límites por plan
Hoy el límite es el mismo para toda clave activa: no hay todavía planes de pago con límites distintos por nivel. Si eso cambia, se anuncia aquí antes de aplicarse — no antes.
Todos los códigos de error y cómo resolverlos
Cada error llega como `application/problem+json` (RFC 9457) con `codigo`, `mensaje`, `sugerencia` y el enlace `documentacion` que apunta a la fila de abajo. Decide siempre por `codigo` (estable), nunca por el texto. `id_peticion` es el mismo valor que la cabecera `X-Request-Id`: dánoslo si nos escribes por un error.
401no_autenticadoFalta la cabecera Authorization con la clave de API.
Manda la clave en la cabecera `Authorization: Bearer <clave>`. La creas en el panel de desarrolladores.
401clave_invalidaLa clave no existe o ha sido revocada.
Comprueba que copiaste la clave entera y que no la has revocado. Crea otra en el panel si hace falta.
401clave_no_es_de_desarrolladorLa clave es de un despacho, no de una cuenta de desarrollador.
Esta API sólo admite claves de una cuenta de desarrollador, no las de un despacho.
403clave_ip_no_permitidaLa clave tiene una lista de direcciones permitidas y esta no está en ella.
La clave tiene una lista de direcciones permitidas. Añade la de tu servidor en el panel, o quita la restricción.
403identidad_sin_verificarLa cuenta aún no tiene la identidad verificada y sin ella no se gasta saldo.
Verifica la identidad de la cuenta en Configuración del panel; sin ella no se gasta saldo.
402saldo_insuficienteNo hay saldo disponible para esta consulta. No se ha servido ni cobrado.
Recarga tu saldo en el panel (Facturación). La consulta no se ha servido ni cobrado.
429demasiadas_peticionesDemasiadas llamadas seguidas con esta clave (120 por minuto).
Espera los segundos que dice la cabecera `Retry-After` y reintenta con espera creciente. El límite es por clave.
400validacionUn dato de la petición no es válido; `campos` dice cuál.
Corrige los campos que indica `campos` y repite la llamada. Una petición inválida no se cobra.
404no_encontradoNo está en lo cargado del BORME, o es una persona que ejerció su derecho de oposición o de supresión.
Comprueba el identificador. Si sólo tienes el nombre, usa `GET /v1/dev/empresas/resolver?q=` o `GET /v1/dev/empresas?q=`. Una persona que ejerció su derecho de oposición o de supresión también da 404.
400cursor_no_validoEl cursor no es válido o ha caducado.
Usa el valor de `siguienteCursor` o de la cabecera `X-Jurilia-Siguiente-Cursor` tal cual lo recibiste.
400campos_no_validosEl parámetro `campos` no es válido.
Usa nombres de campo separados por comas, con puntos para los anidados (`campos=denominacion,cargos.nombre`): hasta 20 campos y 5 niveles.
400idempotency_key_no_validaLa cabecera Idempotency-Key no es válida.
Manda una cadena de 8 a 100 caracteres (letras, cifras, guiones o puntos), distinta para cada creación; un UUID sirve.
400partes_no_validasAlguna parte de `incluir` no existe, o son más de ocho.
Revisa `incluir`: el mensaje dice qué parte no conoce y, si se parece a alguna, cuál quizá querías. Máximo ocho por llamada.
400url_de_aviso_no_validaLa dirección del aviso no cumple las reglas.
La URL debe ser https, con un nombre de dominio público (no una IP), puerto 443 y sin usuario ni contraseña, y debe resolver a direcciones públicas.
400destino_de_aviso_no_seguroEl destino no es público o no se puede resolver.
El destino no es público o no se puede resolver. Usa un dominio público con certificado válido.
400filtro_de_actos_no_validoAlgún grupo de acto del filtro no existe.
Pide los grupos de acto válidos con `GET /v1/dev/avisos/filtros`.
404suscripcion_de_avisos_no_encontradaNo hay esa suscripción de avisos en tu cuenta.
Lista tus suscripciones con `GET /v1/dev/avisos/suscripciones` y usa el `id` que devuelve.
409limite_de_avisosHas alcanzado un tope: cinco suscripciones por cuenta o 500 sociedades vigiladas por suscripción.
Borra una suscripción o una sociedad vigilada que ya no uses. Los topes están en la documentación de avisos.
422empresa_no_vigilableLa sociedad no está en lo cargado, o es un empresario individual (una persona física, que no se vigila).
Sólo se vigilan sociedades que estén en lo cargado del BORME. Busca su identificador con `GET /v1/dev/empresas/resolver?q=`.
400reenvio_no_validoLa fecha del reenvío es futura o anterior a 30 días.
Pide una fecha de los últimos 30 días y no futura, en formato AAAA-MM-DD.
422domicilio_no_vigilableEl domicilio no tiene sociedades en lo cargado, o el identificador no es un slug de domicilio válido.
Usa el slug que devuelve la API (por ejemplo en `GET /v1/dev/empresas/domicilios/{slug}`) de un domicilio con sociedades.
404caso_no_encontradoNo hay ese caso en tu cuenta (o no es tuyo: no se distingue).
Lista tus casos con `GET /v1/dev/casos` y usa el `id` que devuelve.
409caso_cerradoEl caso está cerrado y es de sólo lectura.
Reábrelo con `POST /v1/dev/casos/{id}/reabrir` para añadir, quitar, anotar o editar. Leerlo, sacar su cronología y su informe sí se puede.
404elemento_del_caso_no_encontradoEse elemento no está en el caso.
Mira los elementos del caso con `GET /v1/dev/casos/{id}`: la `referencia` es el id de la sociedad o el slug de la persona o del domicilio.
422elemento_no_anadibleLo que se quiere añadir no está en lo cargado del BORME, es un empresario individual o es una persona que ejerció su oposición o su supresión.
Comprueba la referencia (id de la sociedad, o slug de la persona o del domicilio). Un empresario individual es una persona física y no se añade; una persona que ejerció su derecho de oposición o de supresión ya no existe para el directorio. No se cobra.
409limite_de_casosHas llegado al máximo de 250 casos por cuenta.
Borra algún caso que ya no uses (`DELETE /v1/dev/casos/{id}`) o saca antes su informe.
409limite_de_elementos_del_casoUn caso admite hasta 1.000 elementos.
Quita elementos que ya no hagan falta o abre otro caso para el resto.
400nombre_de_caso_no_validoEl caso necesita un nombre de hasta 120 caracteres.
Manda `nombre` con entre 1 y 120 caracteres.
400texto_de_caso_largoLa descripción (2.000 caracteres) o la nota (5.000) es demasiado larga.
Acorta el texto: la descripción admite 2.000 caracteres y cada nota, 5.000.
404lista_no_encontradaNo hay esa lista en tu cuenta.
Lista tus listas con `GET /v1/dev/listas` y usa el `id` que devuelve.
404etiqueta_no_encontradaNo hay esa etiqueta en tu cuenta.
Lista tus etiquetas con `GET /v1/dev/etiquetas` y usa el `id` que devuelve.
409etiqueta_duplicadaYa existe una etiqueta con ese nombre.
Usa la que ya tienes (`GET /v1/dev/etiquetas`) o elige otro nombre.
400color_de_etiqueta_no_validoEse color no está en la paleta.
Los colores son rojo, naranja, amarillo, verde, azul, morado y gris.
400nota_demasiado_largaLa nota pasa de 5.000 caracteres.
Acorta la nota a 5.000 caracteres como mucho.
422sociedad_no_validaLa sociedad no está en lo cargado del BORME, o es un empresario individual (una persona física).
Busca su identificador con `GET /v1/dev/empresas/resolver?q=`. Listas, etiquetas y notas son sólo de sociedades: un empresario individual es una persona física y no se perfila. No se cobra.
400nombre_del_espacio_no_validoEl nombre es obligatorio y admite hasta 120 caracteres (60 en una etiqueta).
Manda `nombre` con entre 1 y 120 caracteres (entre 1 y 60 en una etiqueta).
409limite_del_espacioHas llegado a un tope de tu cuenta: 100 listas, 5.000 sociedades por lista, 50 etiquetas, 5.000 sociedades por etiqueta o 5.000 notas.
Borra lo que ya no uses. Los topes están en la documentación de cada recurso.
404busqueda_guardada_no_encontradaNo hay esa búsqueda guardada en tu cuenta.
Lista tus búsquedas con `GET /v1/dev/busquedas-guardadas` y usa el `id` que devuelve.
409limite_de_busquedas_guardadasHas llegado al máximo de 100 búsquedas guardadas.
Borra alguna que ya no uses (`DELETE /v1/dev/busquedas-guardadas/{id}`).
400sin_criterioLa búsqueda no tiene ningún filtro que se entienda.
Manda en `parametros` al menos un filtro de `GET /v1/dev/empresas/avanzada` (por ejemplo `provincia=MALAGA&const_anio=2026`).
400busqueda_no_guardableEsa búsqueda no se puede guardar para vigilar sus cambios (por ejemplo, una lista de prospección).
Las listas de prospección (con `acto`) se piden cuando se necesitan con `GET /v1/dev/empresas/prospeccion`. Guarda una búsqueda avanzada normal.
400busqueda_avanzada_no_exportableEsa búsqueda no se puede exportar: no tiene filtros, es demasiado amplia o los datos aún no están preparados.
Añade filtros para acotarla y reintenta en unos minutos si los datos aún no están preparados.
503semaforo_saturadoHay demasiadas búsquedas o informes calculándose a la vez en este momento.
Reintenta en unos segundos con espera creciente. No se ha cobrado nada.
500error_internoUn fallo nuestro. No se cobra nada.
Es un fallo nuestro y no se ha cobrado nada. Reintenta en unos segundos; si persiste, escríbenos con la hora.
422demasiadas_citasEl texto lleva más de 100 citas (un rango «arts. 130 a 133» cuenta como los artículos que abarca).
Divide el texto en varias llamadas. No se cobra.
404resolucion_no_encontradaEsa resolución no está en la biblioteca.
Busca con `GET /v1/dev/jurisprudencia` y usa el `id` que devuelve. Si no está, no la inventamos. No se cobra.
413adjunto_demasiado_grandeLos archivos pasan de algún límite: tamaño, número, páginas, páginas con OCR o píxeles de una imagen.
Manda menos archivos o divide el documento. No se cobra.
415adjunto_tipo_no_admitidoUn archivo no es PDF, Word (.docx), JPEG ni PNG (se mira su contenido, no su nombre).
Conviértelo a .docx o PDF. No se cobra.
422adjunto_ilegibleUn archivo está dañado, tiene contraseña o no se le puede sacar texto.
Prueba con otra foto o con un PDF que lleve el texto dentro. No se cobra.
503ocr_del_asistente_no_disponibleLa lectura OCR está ocupada, es demasiado lenta o no está disponible.
Reintenta con espera creciente. No se cobra.