English

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

400cuerpo_de_validacion

Un parámetro no tiene la forma que pide el endpoint (p. ej. una fecha que no es AAAA-MM-DD).

401no_autenticado

Falta la cabecera Authorization con la clave de API.

401clave_invalida

La clave no existe, está mal escrita o ha sido revocada.

403clave_ip_no_permitida

La 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.

404no_encontrado

La empresa, la persona o el día pedido no están en lo que tenemos cargado del BORME.

404—

La ruta no existe todavía en tu entorno: la plataforma se abre por fases.

402saldo_insuficiente

Sin 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.

402coste_maximo_superado

El peor caso del asistente supera tu `maxCosteCentimos`. No se llama al modelo ni se cobra. Qué hacer: sube el tope o acorta la pregunta.

409—

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.

422—

No se entiende qué artículo se pide en la biblioteca. Qué hacer: escribe la cita como «ET 59» o «art. 59.3 ET».

413adjunto_demasiado_grande

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

415adjunto_tipo_no_admitido

Un 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.

422adjunto_ilegible

Un 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.

502asistente_del_portal_fallo

El modelo ha fallado a medias. No se cobra nada. Qué hacer: reintenta con espera exponencial.

503asistente_del_portal_no_disponible

El asistente no está disponible ahora (sin modelo o sin tarifa). No se cobra. Qué hacer: reintenta más tarde.

503ocr_del_asistente_no_disponible

Hací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.

503asistente_del_portal_no_disponible

Con 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.

500error_interno

Un fallo nuestro. No se cobra. Qué hacer: reintenta alguna vez con espera exponencial y avísanos si persiste.

429demasiadas_peticiones

Se 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-Limit

    El tope de la ventana actual: 120.

  • X-RateLimit-Remaining

    Cuántas llamadas quedan en esta ventana de un minuto.

  • X-RateLimit-Reset

    Cuá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_autenticado

Falta 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_invalida

La 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_desarrollador

La 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_permitida

La 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_verificar

La 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_insuficiente

No 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_peticiones

Demasiadas 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.

400validacion

Un 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_encontrado

No 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_valido

El 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_validos

El 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_valida

La 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_validas

Alguna 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_valida

La 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_seguro

El 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_valido

Algú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_encontrada

No 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_avisos

Has 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_vigilable

La 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_valido

La 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_vigilable

El 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_encontrado

No 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_cerrado

El 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_encontrado

Ese 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_anadible

Lo 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_casos

Has 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_caso

Un caso admite hasta 1.000 elementos.

Quita elementos que ya no hagan falta o abre otro caso para el resto.

400nombre_de_caso_no_valido

El caso necesita un nombre de hasta 120 caracteres.

Manda `nombre` con entre 1 y 120 caracteres.

400texto_de_caso_largo

La 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_encontrada

No hay esa lista en tu cuenta.

Lista tus listas con `GET /v1/dev/listas` y usa el `id` que devuelve.

404etiqueta_no_encontrada

No hay esa etiqueta en tu cuenta.

Lista tus etiquetas con `GET /v1/dev/etiquetas` y usa el `id` que devuelve.

409etiqueta_duplicada

Ya existe una etiqueta con ese nombre.

Usa la que ya tienes (`GET /v1/dev/etiquetas`) o elige otro nombre.

400color_de_etiqueta_no_valido

Ese color no está en la paleta.

Los colores son rojo, naranja, amarillo, verde, azul, morado y gris.

400nota_demasiado_larga

La nota pasa de 5.000 caracteres.

Acorta la nota a 5.000 caracteres como mucho.

422sociedad_no_valida

La 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_valido

El 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_espacio

Has 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_encontrada

No 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_guardadas

Has llegado al máximo de 100 búsquedas guardadas.

Borra alguna que ya no uses (`DELETE /v1/dev/busquedas-guardadas/{id}`).

400sin_criterio

La 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_guardable

Esa 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_exportable

Esa 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_saturado

Hay 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_interno

Un 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_citas

El 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_encontrada

Esa 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_grande

Los 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_admitido

Un 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_ilegible

Un 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_disponible

La lectura OCR está ocupada, es demasiado lenta o no está disponible.

Reintenta con espera creciente. No se cobra.