Errores

Errores

Cada respuesta lleva la cabecera X-Request-Id. Si nos escribes por un problema, indícala: con ella encontramos la llamada en nuestros registros. También puedes mandar tu propio X-Request-Id (de 8 a 64 letras, números, puntos, guiones o guiones bajos) y la respuesta llevará el mismo.

Formato en /v1

Las rutas de /v1 responden los errores en el formato estándar RFC 9457, con Content-Type: application/problem+json:

{
  "type": "https://docs.normatia.com/api-reference/errores/#api_not_enabled",
  "title": "Sin acceso",
  "status": 403,
  "detail": "Tu organización no tiene activado el acceso por API. Escríbenos a hola@normatia.com para activarlo.",
  "code": "api_not_enabled",
  "request_id": "req_4f0c2a9e6b1d4c3e8a7f5b2d1e0c9a8b"
}

• code es lo que debe mirar tu programa. No cambia.
• detail es para una persona y puede cambiar de redacción.
• type enlaza con la explicación del código en esta página.
• Algunos errores llevan datos de más: un 422 de validación trae errors, con el campo y el motivo de cada uno.

Formato en /api/v1 y /api/v2

Las rutas anteriores mantienen su formato, con el código dentro de detail:

{
  "detail": {
    "error": "api_not_enabled",
    "message": "Tu organización no tiene activado el acceso por API. Escríbenos a hola@normatia.com para activarlo."
  }
}

Un error interno (500) responde con este mismo formato, el código internal_error y el request_id.

Note

El servidor MCP responde los errores de autenticación con error y message en la raíz del cuerpo, como piden los clientes MCP. Una clave que no existe recibe solo {"error": "invalid_api_key"}.

Límites por minuto

Las respuestas de las rutas con clave llevan el estado del límite por minuto de su grupo:

Cabecera	Qué indica
RateLimit-Limit	Peticiones permitidas en la ventana
RateLimit-Remaining	Las que quedan
RateLimit-Reset	Segundos hasta que empieza la ventana siguiente

Al pasarse, la respuesta es 429 rate_limit_exceeded con Retry-After, los segundos que hay que esperar.

Códigos

missing_api_key

401. La petición no lleva Authorization: Bearer.

invalid_api_key

401. La clave no empieza por sk-normatia- (o sk-normatia-test-, las de prueba), no existe o está revocada.

api_not_enabled

403. La organización de la clave no tiene activada la API, o el usuario ya no es miembro de ella. Se activa por organización: escribe a hola@normatia.com.

mcp_not_enabled

403. Lo mismo, en el servidor MCP.

insufficient_scope

403. La clave no tiene el permiso que pide la ruta o la herramienta: data, ask o mcp. El que falta va en required_scope y en la cabecera WWW-Authenticate (Bearer error="insufficient_scope", scope="ask"). Crea otra clave con ese permiso; ver Permisos. También lo recibe una clave de prueba o con permisos limitados que intenta revocar otra clave.

not_available_in_sandbox

403. La ruta no responde con una clave de prueba (sk-normatia-test-). Lo que sí responde está en Entorno de pruebas.

test_key_not_supported

403. Una clave de prueba en el servidor MCP, donde no sirve.

not_in_sandbox

404. Con una clave de prueba, la parcela, o el índice o el texto de esa versión de la norma, no está en el entorno de pruebas: de la normativa, solo están los de las versiones curadas a mano. El cuerpo trae sandbox_url.

not_found

404. La ruta, el geo_id, la normativa o la versión no existen.

project_not_found

404. El proyecto no existe o el usuario de la clave no tiene acceso.

no_active_project

400. No se indicó proyecto y el usuario no tiene uno activo.

no_project_location

400. El proyecto no tiene municipio.

validation_error

422. Faltan campos o alguno no es válido. En /v1 el cuerpo trae errors.

invalid_date_range

422. En /v1/usage, la fecha final es anterior a la inicial.

date_range_too_long

422. En /v1/usage, el periodo pasa de 92 días.

payload_too_large

413. El cuerpo pasa de 1 MB.

rate_limit_exceeded

429. Se superó el límite por minuto. Espera los segundos de Retry-After.

quota_exceeded

429. La organización agotó las consultas del mes. El cuerpo trae reset_at.

llm_unavailable

502. El modelo de lenguaje no respondió o no dio una respuesta válida. No consume cuota. Se puede reintentar.

auth_error

503. En el servidor MCP, no se ha podido comprobar la clave porque el servicio de autenticación no responde. No es un problema de la clave: reintenta pasados unos segundos.

internal_error

500. Un fallo nuestro. Escríbenos con el request_id.

Códigos genéricos

Cuando un error de /v1 no tiene un código propio, lleva el genérico de su estado.

bad_request

400. La petición no es válida.

unauthorized

401. Sin autenticar. Lo normal es recibir missing_api_key o invalid_api_key.

forbidden

403. Sin acceso a lo que se pide.

method_not_allowed

405. La ruta existe, pero no con ese método: por ejemplo, un POST a una ruta que solo admite GET.

conflict

409. La petición choca con el estado actual del recurso.

upstream_error

502. Un servicio del que depende la respuesta ha fallado. Se puede reintentar.

service_unavailable

503. El servicio no está disponible ahora mismo. Reintenta tras los segundos de Retry-After, si los trae.

timeout

504. La respuesta ha tardado demasiado. Se puede reintentar.

Códigos de cada recurso

parcel_not_found

404. No tenemos esa parcela: la referencia no existe o su municipio no está en la base territorial. Ver Parcelas.

invalid_ref

422. La referencia catastral no es válida: son 14 caracteres, o los 20 de un inmueble.

invalid_include

422. Un valor de include que no existe. El cuerpo trae allowed, con los que sí.

point_outside_spain

422. El punto está fuera de España: la base territorial solo cubre España.

parcel_data_unavailable

503. Los datos de la parcela no responden ahora mismo. Reintenta tras los segundos de Retry-After.

territory_data_unavailable

503. Lo mismo con las capas y la cobertura de un municipio.

place_not_found

404. No hay ningún lugar con ese identificador (ES- y el código INE). Ver Municipios.

invalid_place

422. El lugar no tiene la forma ES- y el código INE: ES-41091 un municipio, ES-41 una provincia, ES-C01 una comunidad.

invalid_query

422. La búsqueda de lugares está vacía: escribe un nombre o un código INE.

ambiguous_place

422. En el servidor MCP, el nombre del lugar puede ser varios municipios. El mensaje los lista: vuelve a llamar con el geo_id del que corresponda.

regulation_not_found

404. No hay ninguna norma con ese slug. Ver Normativa.

version_not_found

404. La norma no tiene ninguna versión con ese slug, o no tiene versiones publicadas.

section_not_found

404. La versión no tiene ninguna sección con ese slug. El índice está en /contents.

invalid_cursor

422. El cursor no es válido: usa el next_cursor de la respuesta anterior.

key_not_found

404. No hay ninguna clave activa tuya con ese id en la organización. Ver Cuenta.

answer_not_found

404. No hay ninguna consulta tuya con ese id.

invalid_arguments

422. En el servidor MCP, los argumentos de la herramienta no son válidos; por ejemplo, ask con más de uno de project_id, place o parcel.

geo_id_mismatch

422. En /api/v1/verify, el geo_id no es el del proyecto activo. Cambia de proyecto o usa su geo_id.

no_applicable_codes

422. En /api/v1/verify, no hay normativa aplicable en ese lugar, o ninguna de las normas de codes aplica allí.

location_not_found

404. En /api/v1/verify, no hay ningún lugar con ese geo_id.