Errores comunes

Esta página recoge los errores que se repiten en múltiples endpoints de la API, independientemente del recurso al que haga referencia la petición. Provienen de las comprobaciones de autenticación, permisos, existencia de identificadores y formato que se aplican de forma transversal en toda la API.

401 Unauthorized

La petición no se ejecuta porque el usuario de integraciones no tiene acceso al negocio o a la parte de la estructura organizativa a la que pertenece el recurso solicitado.

Business forbidden

El identificador del negocio (businessId) enviado en la petición no coincide con ningún negocio configurado en Orquest.

La respuesta incluye este texto en el campo message.

Cómo resolverlo

El businessId es un identificador de cuenta que se configura a nivel de administración, por lo que no existe ningún endpoint de la API que permita consultarlo.
Se recomienda verificar el identificador con el equipo de Orquest o directamente en la aplicación.

Forbidden

El negocio existe, pero el usuario de integraciones no tiene permisos configurados sobre él.

La respuesta incluye este texto en el campo message.

Cómo resolverlo

Se recomienda revisar el perfil de acceso del usuario de integraciones dentro de la aplicación y comprobar que tiene asignado el negocio.
Si el usuario necesita acceso a toda la información del negocio, se recomienda situarlo en el nodo raíz de la estructura jerárquica, tal y como se detalla en Primeros pasos.

Service or node forbidden

El recurso solicitado (producto, servicio, empleado, etc.) existe, pero pertenece a un nodo o servicio sobre el que el usuario de integraciones no tiene permisos configurados.

La respuesta incluye este texto en el campo message.

Cómo resolverlo

Se recomienda consultar la estructura organizativa del negocio a través de Obtener nodos del negocio u Obtener servicios del negocio, para identificar a qué nodo pertenece el recurso.
Una vez identificado, se recomienda revisar la visibilidad que tiene el usuario sobre ese nodo dentro de la aplicación.

404 Not Found

Un identificador incluido en la petición no coincide con ningún registro dentro del negocio indicado. El mensaje identifica el tipo de recurso que no se ha encontrado, y viaja en el campo message, dentro del array errors.

El texto exacto del mensaje no es uniforme entre endpoints: un mismo recurso no encontrado puede describirse con varias redacciones distintas. Se recomienda identificar el error por el tipo de recurso al que se refiere, y no por una coincidencia exacta de texto.

Empleado no encontrado

El identificador del empleado (employeeId o personId) no coincide con ningún empleado del negocio.

Variantes del mensaje según el endpoint: Employee not found, Person not found, Person <id> does not exist o Could not find employee with id <id>.

Cómo resolverlo

Se recomienda consultar los empleados disponibles a través de Obtener empleados de un servicio u Obtener empleados de un producto. Si solo se quiere comprobar que un identificador concreto existe, Obtener información de un empleado únicamente necesita el businessId y el employeeId.
Se recomienda comprobar también que el identificador utilizado es el identificador externo del empleado y no su identificador interno de Orquest. La diferencia entre ambos se detalla en Identificadores.

Producto no encontrado

El identificador del producto (productId) no coincide con ningún producto del negocio.

Variantes del mensaje según el endpoint: Product not found, Product <id> does not exist o not exits.

Cómo resolverlo

Se recomienda consultar los productos a través de Obtener servicios del negocio, que devuelve los productos vinculados a cada servicio y solo necesita el businessId, u Obtener los productos de un servicio, que es la vía directa cuando ya se conoce el serviceId.

Servicio no encontrado

El identificador del servicio (serviceId) no coincide con ningún servicio del negocio.

El mensaje es not exits.

Cómo resolverlo

Se recomienda consultar los servicios disponibles a través de Obtener servicios del negocio.

Tarea no encontrada

El identificador de la tarea (locationId) no coincide con ninguna tarea configurada en el producto o servicio indicado.

El mensaje es Location not found, que en algunos endpoints llega con un punto final (Location not found.).

Cómo resolverlo

Se recomienda consultar las tareas configuradas a través de Obtener tareas por servicio u Obtener tareas por producto.
Se recomienda comprobar que el identificador coincide con el configurado en Orquest en Diagrama organizativo > Tareas > Id. externo.

Nodo no encontrado

El identificador del nodo (nodeId) no coincide con ningún nodo del negocio.

Variantes del mensaje según el endpoint: Node not found, node not found o Node <id> does not exist.

Cómo resolverlo

Se recomienda consultar la estructura organizativa a través de Obtener nodos del negocio.

Usuario no encontrado

El nombre de usuario (userName) no coincide con ningún usuario del negocio.

El mensaje es User not found.

Cómo resolverlo

Se recomienda consultar los usuarios existentes a través de Obtener todos los usuarios del negocio u Obtener información de un usuario.

406 Not Acceptable

La petición está bien formada, pero alguno de sus valores no se puede interpretar.

date_parser_error

Alguno de los parámetros de fecha de la petición (habitualmente from y to) no tiene un formato válido.

A diferencia del resto de errores de esta página, este texto aparece en el campo cause; el campo message contiene el detalle técnico de la conversión fallida.

Cómo resolverlo

Se recomienda utilizar siempre el formato yyyy-MM-dd en los parámetros de fecha, tal y como se indica en la descripción de cada endpoint.

Resumen

Estos son todos los códigos de respuesta que devuelve la API y el motivo general por el que aparecen.

Código de error A qué se debe

Código de error	A qué se debe
`400 Bad Request`	Alguno de los datos de la petición no supera las validaciones de negocio: campos obligatorios vacíos, valores fuera del rango permitido, rangos de fechas demasiado amplios o datos incoherentes entre sí. El mensaje identifica la comprobación que ha fallado y cada endpoint documenta las suyas en su sección "Códigos de error".
`401 Unauthorized`	El usuario de integraciones no tiene acceso al negocio o a la parte de la estructura organizativa a la que pertenece el recurso solicitado. Para más información, consulta el apartado 401 Unauthorized.
`404 Not Found`	Un identificador incluido en la petición no coincide con ningún registro dentro del negocio indicado. Para más información, consulta el apartado 404 Not Found.
`406 Not Acceptable`	Alguno de los valores de la petición no se puede interpretar o no cumple el formato esperado: fechas mal formadas, campos que no respetan un patrón, valores no admitidos en un campo o límites de tamaño de la petición. Para el caso transversal de las fechas, consulta el apartado 406 Not Acceptable; el resto se documenta en la sección "Códigos de error" de cada endpoint.
`409 Conflict`	La petición entra en conflicto con el estado actual de los datos: un identificador que ya existe, registros duplicados dentro de la propia petición, valores que no coinciden con el catálogo configurado en el negocio u operaciones que sobrescribirían información asociada a otro recurso. Cada endpoint documenta sus casos en su sección "Códigos de error".

400 Bad Request

Alguno de los datos de la petición no supera las validaciones de negocio: campos obligatorios vacíos, valores fuera del rango permitido, rangos de fechas demasiado amplios o datos incoherentes entre sí. El mensaje identifica la comprobación que ha fallado y cada endpoint documenta las suyas en su sección "Códigos de error".

401 Unauthorized

El usuario de integraciones no tiene acceso al negocio o a la parte de la estructura organizativa a la que pertenece el recurso solicitado. Para más información, consulta el apartado 401 Unauthorized.

404 Not Found

Un identificador incluido en la petición no coincide con ningún registro dentro del negocio indicado. Para más información, consulta el apartado 404 Not Found.

406 Not Acceptable

Alguno de los valores de la petición no se puede interpretar o no cumple el formato esperado: fechas mal formadas, campos que no respetan un patrón, valores no admitidos en un campo o límites de tamaño de la petición. Para el caso transversal de las fechas, consulta el apartado 406 Not Acceptable; el resto se documenta en la sección "Códigos de error" de cada endpoint.

409 Conflict

La petición entra en conflicto con el estado actual de los datos: un identificador que ya existe, registros duplicados dentro de la propia petición, valores que no coinciden con el catálogo configurado en el negocio u operaciones que sobrescribirían información asociada a otro recurso. Cada endpoint documenta sus casos en su sección "Códigos de error".