Errores

La API indica las fallas mediante el estado HTTP. El cuerpo de la respuesta sigue uno de estos formatos, así que los clientes en lenguajes fuertemente tipados deben estar preparados para deserializarlos todos.

Formatos

Errores de solicitud (4xx con código)

Las validaciones y reglas de negocio devuelven un código principal y la lista de detalles:

{
  "code": "resourceValidationErr",
  "errors": [
    {
      "code": null,
      "reason": "invalid value",
      "message": "must be a valid id",
      "property": "@.id"
    }
  ]
}

Campo	Tipo	Descripción
code	string	Código principal (ver el catálogo abajo)
errors	array	Detalles de cada problema encontrado
errors[].code	string o null	Código específico del detalle
errors[].reason	string	Motivo del error (p. ej. invalid value, optional)
errors[].message	string	Mensaje legible
errors[].property	string	Ruta de la propiedad que originó el error (p. ej. @.documentNumber; @ indica el identificador de la URL)

Errores de autenticación (401 y 403)

{ "message": "Invalid API Key" }

Vea los mensajes posibles en Autenticación.

Recurso no encontrado (404)

Cuando el identificador es válido pero el recurso no existe, la API devuelve 404 con cuerpo vacío.

Error interno (500)

{
  "errorEventId": "a1b2c3d4e5f6",
  "message": "Internal server error."
}

Envíe el errorEventId al soporte para agilizar la investigación.

Límite de solicitudes (429)

Más de 1 solicitud por segundo devuelve 429. Vea Límite de solicitudes.

Catálogo de códigos

resourceValidationErr

• Estado: 422
• Cuándo ocurre: el cuerpo de la solicitud tiene un campo obligatorio ausente, un tipo incorrecto o un valor fuera de las reglas.
• Causas comunes: campo obligatorio no enviado (reason: optional); CPF/CNPJ inválido o ya registrado en otro cliente (reason: document number already exists); texto por encima del tamaño máximo.
• Cómo resolver: compare el campo indicado en errors[].property con la tabla de campos del endpoint.
• Endpoints de Clientes: crear y actualizar cliente, correo electrónico, teléfono, ubicación; agregar etiqueta; crear respuesta de campo personalizado.
• Endpoints de Colaboradores: crear colaborador (incluye correo electrónico ya usado, reason: duplicated) y actualizar colaborador (incluye identificador inválido en la URL, property: @.id).
• Endpoints de Materiales: crear y actualizar material (al actualizar, incluye identificador inválido en la URL, property: @.id).
• Endpoints de Productos: crear y actualizar producto (incluye code ya usado y, al actualizar, producto inexistente con message: product/service not found).
• Endpoints de Tipos de producto: crear y actualizar tipo de producto (al actualizar, incluye tipo inexistente con message: products type not found).
• Endpoints de Productos y servicios: crear y actualizar producto o servicio (al actualizar, incluye registro inexistente con message: product/service not found).
• Endpoints de Tipos de orden de servicio: crear y actualizar tipo de orden de servicio (al actualizar, incluye identificador inválido en la URL, property: @.id).
• Endpoints de Servicios: crear y actualizar servicio (al actualizar, incluye servicio inexistente con message: work service not found).
• Endpoints de Equipos: crear y actualizar equipo (incluye number o qrCode duplicados, tipo, cliente o campo personalizado no encontrados y, al actualizar, identificador inválido en la URL con property: @.id).
• Endpoints de Tipos de equipo: crear y actualizar tipo de equipo (al actualizar, incluye identificador inválido en la URL, property: @.id).
• Endpoints de Piezas: crear y actualizar pieza (campos obligatorios, name o code duplicados, tipo de pieza inexistente, cantidad mínima negativa), archivar pieza ya archivada, desarchivar pieza activa, y agregar o quitar tipo de equipo.
• Endpoints de Tipos de pieza: crear y actualizar tipo de pieza (name ausente o duplicado), archivar tipo ya archivado y desarchivar tipo activo.
• Endpoints de Unidades de pieza: crear y actualizar unidad (campos obligatorios, pieza o inventario inexistentes, campo de situación enviado) y acciones con situación incompatible (reason: invalid status) o inventario de clasificación en la liberación.
• Endpoints de Depósitos: crear y actualizar depósito (incluye nombre ya usado y, al actualizar, depósito inexistente con message: storage not found).
• Endpoints de Movimientos: realizar movimiento y transferencia por identificador externo (producto, depósito u orden inexistentes, saldo insuficiente, cantidad inválida).
• Endpoints de Vehículos: crear y actualizar vehículo (incluye marca o modelo no encontrados por el nombre y, al actualizar, vehículo inexistente con message: vehicle not found).
• Endpoints de Órdenes de servicio: crear y actualizar orden (incluye cliente, tipo de orden de servicio, ubicación, solicitud, contrato o acuerdo no encontrados, número duplicado y, al actualizar, identificador inválido en la URL); crear y actualizar actividad; adjuntar archivo; comentar; vincular equipo o etiqueta; agregar producto o servicio; quitar producto (v2); modificar respuestas de formulario.
• Endpoints de Actividades: agregar y quitar colaborador secundario.
• Endpoints de Solicitudes de servicio: crear y actualizar solicitud.
• Endpoints de Presupuestos: crear, actualizar, rechazar y cancelar presupuesto (incluye presupuesto inexistente y situación que no permite la acción); agregar etiqueta.
• Endpoints de Formularios respondidos: modificar respuestas.
• Endpoints de Carga de archivos: enviar archivo.

parametersValidationErr

• Estado: 422
• Cuándo ocurre: un parámetro de query es inválido.
• Causas comunes: limit fuera de 1–100; offset fuera de 0–200000; valor de sort no aceptado; fecha inválida en un filtro (created_at>=:2026-02-31).
• Cómo resolver: vea Paginación y Filtros y ordenación.
• Endpoints de Clientes: todos los listados.
• Endpoints de Colaboradores: listar colaboradores.
• Endpoints de Materiales: listar materiales.
• Endpoints de Productos: listar productos.
• Endpoints de Tipos de producto: listar tipos de producto.
• Endpoints de Productos y servicios: listar productos y servicios.
• Endpoints de Tipos de orden de servicio: listar tipos de orden de servicio.
• Endpoints de Servicios: listar servicios.
• Endpoints de Equipos: listar equipos.
• Endpoints de Tipos de equipo: listar tipos de equipo.
• Endpoints de Piezas: listar piezas.
• Endpoints de Tipos de pieza: listar tipos de pieza.
• Endpoints de Unidades de pieza: listar unidades de pieza.
• Endpoints de Depósitos: listar depósitos.
• Endpoints de Movimientos: listar movimientos y transferencias.
• Endpoints de Vehículos: listar vehículos, marcas, modelos y usos.
• Endpoints de Órdenes de servicio: listar órdenes y actividades de la orden.
• Endpoints de Actividades: listar actividades y colaboradores secundarios.
• Endpoints de Solicitudes de servicio: listar solicitudes.
• Endpoints de Presupuestos: listar presupuestos.
• Endpoints de Etiquetas, Evaluaciones, Acuerdos de servicio y Contratos de plazos: listados.

uriValidationErr

• Estado: 422
• Cuándo ocurre: el identificador de la URL no es válido o pertenece a otra cuenta.
• Causas comunes: identificador mal escrito o truncado; identificador de otro ambiente o de otra cuenta.
• Cómo resolver: use el id exactamente como lo devuelve la API. Un identificador válido que no existe devuelve 404, no este error.
• Endpoints de Clientes: todos los que reciben un identificador en la URL.
• Endpoints de Colaboradores: recuperar colaborador.
• Endpoints de Materiales: recuperar material.
• Endpoints de Productos: recuperar y actualizar producto.
• Endpoints de Tipos de producto: recuperar y actualizar tipo de producto.
• Endpoints de Productos y servicios: recuperar y actualizar producto o servicio.
• Endpoints de Tipos de orden de servicio: recuperar tipo de orden de servicio y listar sus campos personalizados.
• Endpoints de Servicios: recuperar y actualizar servicio.
• Endpoints de Equipos: recuperar equipo.
• Endpoints de Tipos de equipo: recuperar tipo de equipo.
• Endpoints de Piezas: recuperar, archivar, desarchivar y agregar o quitar tipo de equipo.
• Endpoints de Tipos de pieza: recuperar, archivar y desarchivar tipo de pieza.
• Endpoints de Unidades de pieza: recuperar unidad y todas las acciones.
• Endpoints de Depósitos: recuperar y actualizar depósito.
• Endpoints de Movimientos: recuperar movimiento.
• Endpoints de Vehículos: recuperar y actualizar vehículo, y recuperar uso de vehículo.
• Endpoints de Órdenes de servicio: todos los que reciben el identificador de la orden o del ítem en la URL.
• Endpoints de Actividades: recuperar actividad y gestionar colaboradores secundarios.
• Endpoints de Solicitudes de servicio: recuperar solicitud.
• Endpoints de Presupuestos: recuperar y actualizar presupuesto; gestionar etiquetas.
• Endpoints de Formularios respondidos: recuperar y modificar formulario.
• Endpoints de Etiquetas, Evaluaciones, Acuerdos de servicio y Contratos de plazos: recuperar acuerdo o contrato.

resourceAlreadyExists

• Estado: 409
• Cuándo ocurre: el recurso que intenta crear o vincular ya existe.
• Causas comunes: agregar al cliente una etiqueta que ya está vinculada.
• Cómo resolver: consulte el recurso antes de crearlo, o trate el 409 como éxito cuando el objetivo sea garantizar el vínculo.
• Endpoints de Clientes: agregar etiqueta al cliente.
• Endpoints de Tipos de equipo: crear y actualizar tipo de equipo con un nombre ya usado en la cuenta.
• Endpoints de Órdenes de servicio: vincular equipo, agregar etiqueta y agregar servicio ya presentes en la orden.
• Endpoints de Presupuestos: agregar etiqueta ya presente en el presupuesto.

resourceNotAllowed

• Estado: 422
• Cuándo ocurre: la operación no está permitida para el recurso en el estado actual.
• Cómo resolver: lea errors[].message para saber qué regla impidió la operación.
• Endpoints de Clientes: ninguno.
• Endpoints de Depósitos: todos, cuando la cuenta no tiene el módulo de control de inventario (reason: storage control disabled).
• Endpoints de Movimientos: todos, cuando la cuenta no tiene el módulo de control de inventario.

resourceNotFoundErr

• Estado: 422
• Cuándo ocurre: no se encontró un recurso referenciado en el cuerpo de la solicitud (distinto del 404, que indica que el recurso de la URL no existe).
• Cómo resolver: verifique el identificador indicado en errors[].property.
• Endpoints de Clientes: ninguno.

resourceNotFound

• Estado: 422
• Cuándo ocurre: el recurso de la URL no existe, en endpoints de piezas, tipos de pieza y unidades de pieza (en esos endpoints no hay 404).
• Causas comunes: identificador de un recurso borrado o de otro ambiente.
• Cómo resolver: verifique el identificador; liste los recursos para obtener un id válido. Observe que el código no termina en Err, a diferencia de resourceNotFoundErr.

resourceLockedErr

• Estado: 422
• Cuándo ocurre: el recurso está bloqueado para modificaciones (p. ej. una orden de servicio finalizada).
• Endpoints de Clientes: ninguno.
• Endpoints de Piezas: actualizar, archivar, desarchivar y agregar o quitar tipo de equipo de una pieza inexistente.
• Endpoints de Tipos de pieza: actualizar, archivar y desarchivar un tipo de pieza inexistente.
• Endpoints de Unidades de pieza: instalar, desinstalar, descartar, devolver y liberar una unidad inexistente.
• Endpoints de Órdenes de servicio: modificar respuestas de formulario de una orden bloqueada.
• Endpoints de Formularios respondidos: modificar respuestas de formulario de una orden bloqueada.

cannotArchivePrimaryLocation

• Estado: 422
• Cuándo ocurre: intento de archivar (archived: true) la ubicación principal de un cliente.
• Cómo resolver: defina otra ubicación como principal antes de archivar esta.
• Endpoints de Clientes: actualizar ubicación del cliente.

cannotChangeCustomerOfPrimaryLocation

• Estado: 422
• Cuándo ocurre: intento de mover la ubicación principal a otro cliente.
• Cómo resolver: defina otra ubicación como principal en el cliente actual antes de mover esta.
• Endpoints de Clientes: actualizar ubicación del cliente.

cannotSetArchivedLocationAsPrimary

• Estado: 422
• Cuándo ocurre: intento de definir como principal una ubicación archivada.
• Cómo resolver: desarchive la ubicación antes (archived: false).
• Endpoints de Clientes: actualizar ubicación principal.