Códigos de error

Toda respuesta de error de la API tiene este shape:

{
  "status": "failed",
  "code": "ASSET_NOT_FOUND",
  "message": "Activo no encontrado",
  "requestId": "b2f8c9e0-…"
}

code: código estable — es el campo para hacer branching en el cliente.
message: mensaje legible, seguro para mostrar al usuario final.
requestId: identificador de la request. Incluilo si reportás un problema al soporte.
Los errores de validación agregan errors: [{ path, message }] con el detalle por campo.

Algunos endpoints todavía devuelven códigos con la forma ERR_<status> (por ejemplo ERR_409). Esos no son estables: no hagas branching sobre ellos. Los códigos del catálogo de abajo sí lo son.

Errores de servicios externos

Cuando falla un proveedor externo, la API responde un código de la familia <PROVEEDOR>_HTTP_<status> / NAVIXY_STATUS_<n> con un mensaje traducido y el status real del fallo (400/404/409/429 se conservan; fallos de infraestructura o de credenciales de la integración responden 502). Estos códigos son dinámicos y no aparecen como entradas de este catálogo; el prefijo identifica la integración.

Catálogo

Transversales

Código	HTTP	Mensaje al cliente
`INTERNAL_ERROR`	500	Error interno del servidor
`VALIDATION_ERROR`	400	Error de validacion
`ROUTE_NOT_FOUND`	404	Ruta no encontrada
`SERVICE_ERROR`	502	Error en el servicio. Intente nuevamente mas tarde.
`NAVIXY_REQUEST_FAILED`	502	El servicio externo no devolvió una respuesta válida. Intenta nuevamente.
`RATE_LIMITED`	429	Demasiadas solicitudes. Intente nuevamente mas tarde.
`DATABASE_ERROR`	500	Error interno del servidor
`DB_NOT_READY`	500	Base de datos no disponible
`NOT_READY`	503	El servicio no está listo para recibir tráfico
`NOT_FOUND`	404	Recurso no encontrado
`UNAUTHORIZED`	401	No autorizado
`FORBIDDEN`	403	Acceso denegado
`PERMISSION_DENIED`	403	No tienes permiso para realizar esta acción
`PERMISSION_CHECK_FAILED`	500	Error al verificar permisos
`INVALID_OBJECT_ID`	400	Identificador invalido
`INVALID_EXPORT_FORMAT`	400	Formato de exportacion no soportado
`INVALID_CLIENT`	400	Cliente inválido
`FILE_UPLOAD_ERROR`	400	Archivo inválido o no permitido

Autenticación y sesión

Código	HTTP	Mensaje al cliente
`SESSION_REQUIRED`	401	No hay sesion activa
`SESSION_CREDENTIAL_REQUIRED`	403	Esta accion requiere una sesion de usuario
`AUTH_BAD_REQUEST`	400	Solicitud de autenticacion invalida
`AUTH_UNAUTHORIZED`	401	Credenciales invalidas o sesion expirada
`AUTH_FORBIDDEN`	403	No tiene permisos para realizar esta accion
`AUTH_NOT_FOUND`	404	Cuenta no encontrada
`AUTH_SERVICE_UNAVAILABLE`	503	Servicio de autenticacion no disponible
`USER_INACTIVE`	403	Usuario inactivo
`CLIENT_INACTIVE`	403	Cliente inactivo
`API_TOKEN_INVALID`	401	API token invalido, expirado o revocado
`API_TOKEN_USER_NOT_FOUND`	401	Usuario asociado al API token no encontrado
`API_TOKEN_USER_INACTIVE`	403	Usuario asociado al API token inactivo
`API_TOKEN_CLIENT_INACTIVE`	403	Cliente asociado al API token inactivo
`API_TOKEN_VALIDATION_ERROR`	401	No se pudo validar el API token
`INVALID_CODE`	401	Código de verificación incorrecto
`OTP_HAS_EXPIRED`	401	El código expiró. Solicita uno nuevo.
`TOO_MANY_ATTEMPTS_REQUEST_NEW_CODE`	401	Demasiados intentos. Solicita un código nuevo.
`INVALID_TWO_FACTOR_COOKIE`	401	La verificación expiró. Vuelve a iniciar sesión.
`MOBILE_TWO_FACTOR_OTP_SEND_FAILED`	502	No se pudo enviar el código de verificación. Intenta nuevamente.
`MOBILE_TWO_FACTOR_NOT_SUPPORTED`	403	La verificación en dos pasos requiere una versión más reciente de la aplicación. Actualízala para ingresar.
`MOBILE_SIGN_IN_NO_TOKEN`	500	No se pudo iniciar sesión. Intenta nuevamente en unos momentos.
`AUTH_OPERATION_FAILED`	500	No se pudo completar la operación de autenticación

Recursos no encontrados

Código	HTTP	Mensaje al cliente
`ASSET_NOT_FOUND`	404	Activo no encontrado
`CLIENT_NOT_FOUND`	404	Cliente no encontrado
`GEOFENCE_NOT_FOUND`	404	Geocerca no encontrada
`GEOZONE_NOT_FOUND`	404	Geozona no encontrada
`EXECUTION_NOT_FOUND`	404	Ejecucion de reporte no encontrada
`SCHEDULED_REPORT_NOT_FOUND`	404	Reporte programado no encontrado
`APP_FORM_NOT_FOUND`	404	Formulario no encontrado
`FORM_TEMPLATE_NOT_FOUND`	404	Plantilla de formulario no encontrada
`KML_NOT_FOUND`	404	Archivo KML no encontrado
`ROAD_SPEED_LIMIT_NOT_FOUND`	404	Limite de velocidad de via no encontrado
`USER_NOT_FOUND`	404	Usuario no encontrado
`ROLE_NOT_FOUND`	404	Rol no encontrado
`TRACKER_NOT_FOUND`	404	Dispositivo no encontrado
`ALERT_NOT_FOUND`	404	Alerta no encontrada
`ALERT_TRIGGER_NOT_FOUND`	404	Disparador no encontrado
`MAINTENANCE_NOT_FOUND`	404	Recurso de mantenimiento no encontrado
`PEDIDO_NOT_FOUND`	404	Pedido no encontrado
`TRANSPORTISTA_NOT_FOUND`	404	Transportista no encontrado
`CARGO_UBICACION_NOT_FOUND`	404	Ubicación no encontrada
`PLACE_NOT_FOUND`	404	POI no encontrado
`TRIP_NOT_FOUND`	404	Viaje no encontrado
`STOP_NOT_FOUND`	404	Parada entre viajes no encontrada
`NOTIFICATION_NOT_FOUND`	404	Notificación no encontrada
`ASSET_GROUP_NOT_FOUND`	404	Grupo de activos no encontrado
`LAYER_NOT_FOUND`	404	Capa no encontrada
`DRIVER_NOT_FOUND`	404	Conductor no encontrado
`TASK_IMPORT_NOT_FOUND`	404	Registro de importación no encontrado

Usuarios

Código	HTTP	Mensaje al cliente
`USER_PROTECTED`	403	No se puede eliminar un usuario protegido
`USER_DELETE_FORBIDDEN`	403	No tienes permisos para eliminar este usuario
`USER_PASSWORD_CHANGE_FORBIDDEN`	403	No tienes permisos para cambiar esta contraseña
`ROLE_PROTECTED`	403	No se puede eliminar un rol protegido
`ROLE_FORBIDDEN`	403	No tienes permisos para asignar usuarios a roles protegidos o con acceso al panel de administración
`ROLE_CONFLICT`	409	No se puede eliminar el rol porque está asignado a usuarios
`ROLE_INVALID_PERMISSIONS`	400	Hay permisos bloqueados por restricciones del cliente
`ROLE_INVALID_ASSIGNMENT`	400	Uno o más usuarios asignados no pertenecen al cliente o no se pueden modificar
`ROLE_OPERATION_FAILED`	500	Error al procesar el rol

Trackers

Código	HTTP	Mensaje al cliente
`TRACKER_ALREADY_LINKED`	409	Ese dispositivo ya está registrado
`TRACKER_IDENT_MISMATCH`	409	El IMEI no coincide con el del dispositivo registrado
`TRACKER_FLESPI_ID_INVALID`	500	El dispositivo tiene una configuración inválida. Contacta a soporte
`TRACKER_FLESPI_IDENT_MISSING`	400	El dispositivo no tiene IMEI configurado
`TRACKER_FLESPI_CREATE_REJECTED`	400	No se pudo dar de alta el dispositivo: revisa el IMEI y el modelo
`TRACKER_FLESPI_CREATE_FAILED`	500	No se pudo crear el dispositivo
`TRACKER_FLESPI_DELETE_FAILED`	500	No se pudo eliminar el dispositivo
`TRACKER_PROVISIONING_ENQUEUE_FAILED`	503	El dispositivo quedó registrado pero no se pudo sincronizar. Intenta de nuevo en unos minutos

Fechas y rangos

Código	HTTP	Mensaje al cliente
`DATE_RANGE_INVALID`	400	Rango de fechas invalido
`DATE_RANGE_REQUIRED`	400	El rango de fechas es requerido
`DATE_RANGE_TOO_LARGE`	400	El rango de fechas es demasiado amplio
`DATE_FROM_REQUIRED`	400	La fecha de inicio es requerida
`DATE_TO_REQUIRED`	400	La fecha de termino es requerida
`INVALID_DATE_FORMAT`	400	Formato de fecha invalido
`INVALID_DATE_RANGE`	400	Rango de fechas invalido
`INVALID_TIME_FORMAT`	400	Formato de hora invalido
`MISSING_DATE_RANGE`	400	El rango de fechas es requerido

Geozonas / KML

Código	HTTP	Mensaje al cliente
`KML_TOO_LARGE`	413	El archivo KML supera el tamano maximo permitido
`KML_PARSE_ERROR`	400	No se pudo interpretar el archivo KML
`KML_READ_ERROR`	400	Error al leer el archivo KML
`KML_PROCESSING_ERROR`	400	No se pudo procesar el archivo KML
`KMZ_DECOMPRESS_ERROR`	400	Error al descomprimir el archivo KMZ
`KMZ_WITHOUT_KML`	400	El KMZ no contiene un archivo KML
`KML_PLACEMARK_LIMIT`	400	El archivo KML supera el limite de elementos
`EMPTY_POLYGON`	400	El poligono no tiene coordenadas validas
`UNSUPPORTED_GEOZONE_GEOMETRY`	400	Geometria de geozona no soportada

Geocodificación

Código	HTTP	Mensaje al cliente
`GEOCODING_COORDINATES_INVALID`	400	Coordenadas inválidas
`GEOCODING_QUERY_INVALID`	400	La dirección debe tener al menos 4 caracteres
`GEOCODING_PROVIDER_FAILED`	500	El servicio de geocodificación no está disponible
`GEOCODING_OPERATION_FAILED`	500	Error al procesar la solicitud de geocodificación

Precios de combustible

Código	HTTP	Mensaje al cliente
`FUEL_PRICE_OPERATION_FAILED`	500	Error al procesar la solicitud de precios de combustible

Formularios

Código	HTTP	Mensaje al cliente
`FORM_FIELD_REQUIRED`	400	Falta un campo requerido del formulario
`FORM_FIELD_INVALID_TYPE`	400	Un campo del formulario tiene un tipo invalido
`FORM_FIELD_INVALID_OPTION`	400	Un campo del formulario tiene una opcion invalida
`FORM_FIELD_INVALID_EMAIL`	400	Un campo del formulario tiene un email invalido
`FORM_FIELD_INVALID_DATE`	400	Un campo del formulario tiene una fecha invalida
`FORM_OPERATION_FAILED`	500	Error al procesar el formulario

Reportes y alertas

Código	HTTP	Mensaje al cliente
`UNSUPPORTED_REPORT_TYPE`	400	Tipo de reporte no soportado
`UNSUPPORTED_ALERT_TYPE`	400	Tipo de alerta no soportado
`CHECKIN_REPORT_TOO_LARGE`	413	El reporte supera el tamano maximo; acote el rango
`NO_VISIBLE_TRACKERS`	403	No hay dispositivos disponibles para generar el reporte
`SPEED_LIMIT_REQUIRED`	400	El limite de velocidad es requerido para alertas de velocidad
`ALERT_LIMIT_EXCEEDED`	400	Limite de alertas alcanzado para el dispositivo
`GEOFENCE_FORBIDDEN`	403	La geocerca indicada pertenece a otro cliente
`GEOFENCE_CONFLICT`	409	La geocerca indicada es ambigua para este cliente
`GEOFENCE_SYNC_FAILED`	500	Error al sincronizar la geocerca
`GEOFENCE_OPERATION_FAILED`	500	Error al procesar la geocerca
`SCHEDULED_REPORT_INVALID_UPDATE`	400	No se permite modificar el tipo de reporte (reportType)
`SCHEDULED_REPORT_OPERATION_FAILED`	500	Error al procesar el reporte programado
`TRACKER_OPERATION_FAILED`	500	No se pudo completar la operación sobre el dispositivo
`TRIP_OPERATION_FAILED`	500	Error al procesar el viaje
`USER_OPERATION_FAILED`	500	Error al procesar el usuario
`NOTIFICATION_OPERATION_FAILED`	500	Error al procesar la notificación
`ALERT_FORBIDDEN`	403	La alerta no se puede modificar manualmente
`ALERT_GEOFENCE_REQUIRED`	400	La geocerca es requerida para alertas de geocerca
`ALERT_ASSET_CONFLICT`	409	Los dispositivos ya están asignados a otra alerta del mismo tipo
`ALERT_CONFIGURATION_FAILED`	500	Error al configurar la alerta
`ALERT_SYNC_FAILED`	500	Error al sincronizar los dispositivos de la alerta
`ALERT_OPERATION_FAILED`	500	Error al procesar la alerta
`REPORT_OPERATION_FAILED`	500	Error al generar el reporte
`NAVIXY_PLATFORM_NOT_CONFIGURED`	400	La cuenta no tiene esa plataforma de rastreo configurada

Unicidad de recursos

Código	HTTP	Mensaje al cliente
`USER_EMAIL_ALREADY_EXISTS`	409	Ya existe un usuario con ese email
`TRACKER_IMEI_ALREADY_EXISTS`	409	Ya existe un dispositivo con ese IMEI
`ALERT_TRIGGER_ALREADY_EXISTS`	400	Ya existe un disparador con el mismo nombre
`ROLE_ALREADY_EXISTS`	409	Ya existe un rol con el mismo nombre para este cliente
`ASSET_ALREADY_EXISTS`	400	Ya existe un activo con el mismo nombre para este cliente
`DRIVER_ALREADY_EXISTS`	400	Ya existe un conductor con el mismo RUT
`ASSET_GROUP_ALREADY_EXISTS`	400	Ya existe un grupo de activos con este nombre para este cliente.

Check-ins (formularios dinámicos)

Código	HTTP	Mensaje al cliente
`CHECKIN_TEMPLATE_NOT_FOUND`	404	Formulario de check-in no encontrado
`CHECKIN_NOT_FOUND`	404	Check-in no encontrado
`CHECKIN_FIELD_TYPE_CHANGED`	400	No se puede cambiar el tipo de un campo existente; crea un campo nuevo
`CHECKIN_VALUES_INVALID`	400	Las respuestas del formulario no son válidas
`CHECKIN_ASSET_NOT_FOUND`	404	Activo no encontrado
`CHECKIN_UNSUPPORTED_MIME_TYPE`	400	Tipo de archivo no soportado
`CHECKIN_FORM_NOT_FOUND`	404	El check-in no tiene un formulario asociado.
`CHECKIN_OPERATION_FAILED`	500	Error al procesar el check-in

Pedidos (cargo)

Código	HTTP	Mensaje al cliente
`PEDIDO_VEHICLE_MOVING_CONFLICT`	409	El vehículo ya tiene un pedido en movimiento (detectado por índice único).
`PEDIDO_INVALID_TRANSITION`	409	Transición de estado inválida
`PEDIDO_CONCURRENT_MODIFICATION`	409	El estado del pedido cambió concurrentemente. Recarga e intenta nuevamente.
`ETA_CALCULATION_FAILED`	503	No se pudo calcular la ETA. Ingresa la ETA manualmente.
`PEDIDO_OPERATION_FAILED`	500	Error al procesar el pedido
`CARGO_OPERATION_FAILED`	500	Error al procesar la operación de cargo

Consulta vehicular

Código	HTTP	Mensaje al cliente
`VEHICLE_LOOKUP_INVALID`	400	Consulta vehicular inválida
`VEHICLE_LOOKUP_NOT_FOUND`	404	No se encontró información para la patente consultada
`VEHICLE_LOOKUP_UNAVAILABLE`	503	El servicio de consulta vehicular no está disponible temporalmente
`VEHICLE_LOOKUP_OPERATION_FAILED`	500	Error al procesar la consulta vehicular

Mensajes de dispositivos (export a Parquet)

Código	HTTP	Mensaje al cliente
`DEVICE_MESSAGE_EXPORT_COUNT_MISMATCH`	500	Error en la exportación de mensajes de dispositivos
`DEVICE_MESSAGE_EXPORT_EMPTY_DAY`	500	Error en la exportación de mensajes de dispositivos
`DEVICE_MESSAGE_EXPORT_REGRESSION`	500	Error en la exportación de mensajes de dispositivos
`AZURE_CONFIG_MISSING`	500	Error de configuración del almacenamiento
`AZURE_CREDENTIALS_ERROR`	500	No se pudo acceder al almacenamiento

Terreno (work)

Código	HTTP	Mensaje al cliente
`TASK_BULK_NOT_FOUND`	404	Operación masiva no encontrada.
`EMPLOYEE_LOCATION_NOT_FOUND`	400	No se encontró la ubicación de la dirección indicada.
`WORK_OPERATION_FAILED`	500	Error al procesar la operación de terreno

Administración

Código	HTTP	Mensaje al cliente
`CLIENT_CONFLICT`	409	No se puede eliminar el cliente porque tiene recursos asociados
`CLIENT_UPDATE_FAILED`	500	Error al actualizar el cliente
`ADMIN_OPERATION_FAILED`	500	Error al procesar la operación de administración

Mantenimiento

Código	HTTP	Mensaje al cliente
`MAINTENANCE_PART_CONFLICT`	400	No se puede eliminar la parte porque tiene stock asociado
`MAINTENANCE_OPERATION_FAILED`	500	Error al procesar la operación de mantenimiento

Activos y grupos

Código	HTTP	Mensaje al cliente
`ASSET_TYPE_NOT_FOUND`	404	AssetType no encontrado
`ASSET_OPERATION_FAILED`	500	Error al procesar el activo
`ASSET_GROUP_OPERATION_FAILED`	500	Error al procesar el grupo de activos
`LAYER_OPERATION_FAILED`	500	Error al procesar la capa
`DRIVER_OPERATION_FAILED`	500	Error al procesar el conductor
`PLACE_OPERATION_FAILED`	500	Error al procesar el POI

Empezar

Fundamentos

Integración

Errores de servicios externos

Catálogo

Transversales

Autenticación y sesión

Recursos no encontrados

Usuarios

Trackers

Fechas y rangos

Geozonas / KML

Geocodificación

Precios de combustible

Formularios

Reportes y alertas

Unicidad de recursos

Check-ins (formularios dinámicos)

Pedidos (cargo)

Consulta vehicular

Mensajes de dispositivos (export a Parquet)

Terreno (work)

Administración

Mantenimiento

Activos y grupos

​Errores de servicios externos

​Catálogo

​Transversales

​Autenticación y sesión

​Recursos no encontrados

​Usuarios

​Trackers

​Fechas y rangos

​Geozonas / KML

​Geocodificación

​Precios de combustible

​Formularios

​Reportes y alertas

​Unicidad de recursos

​Check-ins (formularios dinámicos)

​Pedidos (cargo)

​Consulta vehicular

​Mensajes de dispositivos (export a Parquet)

​Terreno (work)

​Administración

​Mantenimiento

​Activos y grupos

Errores de servicios externos

Catálogo

Transversales

Autenticación y sesión

Recursos no encontrados

Usuarios

Trackers

Fechas y rangos

Geozonas / KML

Geocodificación

Precios de combustible

Formularios

Reportes y alertas

Unicidad de recursos

Check-ins (formularios dinámicos)

Pedidos (cargo)

Consulta vehicular

Mensajes de dispositivos (export a Parquet)

Terreno (work)

Administración

Mantenimiento

Activos y grupos