Códigos de error - UGPS Atlas API

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 SERVICE_ERROR con HTTP 502 y un mensaje traducido. Los códigos internos de esa familia no cruzan al cliente, así que no aparecen en este catálogo.

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

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	Tracker 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

Trackers

Código	HTTP	Mensaje al cliente
`TRACKER_ALREADY_LINKED`	409	El dispositivo Flespi ya está enlazado a un tracker
`TRACKER_IDENT_MISMATCH`	409	El identificador no coincide con el dispositivo Flespi
`TRACKER_FLESPI_ID_INVALID`	500	El tracker no tiene un flespiId válido
`TRACKER_FLESPI_IDENT_MISSING`	400	El dispositivo Flespi no tiene identificador configurado
`TRACKER_FLESPI_CREATE_REJECTED`	400	Flespi rechazó la creación del dispositivo
`TRACKER_FLESPI_CREATE_FAILED`	500	Error al crear el dispositivo en Flespi
`TRACKER_FLESPI_DELETE_FAILED`	500	Error al eliminar el dispositivo de Flespi
`TRACKER_TRIP_CONFIG_REASSIGN_FAILED`	502	Error al reasignar el calculator de trips. El cambio de trip_config fue revertido.
`TRACKER_PROVISIONING_ENQUEUE_FAILED`	503	No se pudo encolar la sincronización con Flespi. El tracker quedó marcado con error de provisioning.

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

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

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 trackers visibles 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

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 tracker con ese IMEI

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

​Errores de servicios externos

​Catálogo

​Transversales

​Autenticación y sesión

​Recursos no encontrados

​Usuarios

​Trackers

​Fechas y rangos

​Geozonas / KML

​Formularios

​Reportes y alertas

​Unicidad de recursos

​Check-ins (formularios dinámicos)

Errores de servicios externos

Catálogo

Transversales

Autenticación y sesión

Recursos no encontrados

Usuarios

Trackers

Fechas y rangos

Geozonas / KML

Formularios

Reportes y alertas

Unicidad de recursos

Check-ins (formularios dinámicos)