Saltar a contenido

Errores de Fichaje (v2)

Este documento lista los códigos, mensajes y condiciones de error para fichaje en v2.

Validación de entrada (Zod)

Ruta: POST /api/v2/timerecord/start - HTTP 400 con detalles de validación. Códigos personalizados en params.code: - REQUIRED_LATITUDE: falta latitude. - INVALID_LATITUDE_NUMBER: latitude no es numérico. - INVALID_LATITUDE_RANGE: latitude fuera de [-90, 90]. - REQUIRED_LONGITUDE: falta longitude. - INVALID_LONGITUDE_NUMBER: longitude no es numérico. - INVALID_LONGITUDE_RANGE: longitude fuera de [-180, 180].

Ejemplo de respuesta 400: 

{
  "status": "fail",
  "message": "Validation error",
  "error": {
    "issues": [
      { "message": "latitude es requerido", "params": { "code": "REQUIRED_LATITUDE" } }
    ]
  }
}

Autenticación

  • NO_PROVIDER_TOKEN
  • HTTP 401
  • message: "No provider token"
  • Cuándo: falta/incorrecto Authorization: Bearer <token>.

Errores de negocio – ENTRADA (Start)

Origen: StartTimeRecordUseCase

  • EMPLOYEE_ID_REQUIRED
  • HTTP 400
  • message: "Employee ID is required"

  • Falta employeeId en el token.

  • EMPLOYEE_NOT_FOUND

  • HTTP 404
  • message: "Employee not found"

  • El empleado del token no existe.

  • NO_SCHEDULE_TODAY

  • HTTP 403
  • message: "You do not have scheduled classes today to start a time record (it may be because your events have no students assigned)"

  • Empleado NO flexible sin clases hoy.

  • OUT_OF_SCHEDULE_WINDOW

  • HTTP 403
  • message: "You are outside your scheduled class time window"

  • Empleado NO flexible fuera de la ventana de ENTRADA: 5 minutos antes y 5 minutos después del inicio de la clase (Europe/Madrid + DST).

  • OUT_OF_RANGE

  • HTTP 403
  • message: "You are not within the allowed range of any of your assigned centers"
  • Coordenadas fuera de la geovalla de alguno de sus centros asignados.
  • Radio configurable: GEOFENCE_RADIUS_METERS (por defecto 100m).

Errores de negocio – SALIDA (End)

Origen: EndTimeRecordUseCase

  • EMPLOYEE_ID_REQUIRED
  • HTTP 400
  • message: "Employee ID is required"

  • Falta employeeId en el token.

  • EMPLOYEE_NOT_FOUND

  • HTTP 404
  • message: "Employee not found"

  • El empleado del token no existe.

  • NO_OPEN_TIME_RECORD

  • HTTP 409
  • message: "No open time record to close"

  • No hay un fichaje abierto pendiente de cierre para el empleado.

  • OUT_OF_RANGE

  • HTTP 403
  • message: "You are not within the allowed range of any of your assigned centers"

  • Fuera de la geovalla en el momento de la salida.

  • EARLY_EXIT

  • HTTP 403
  • message: "You are leaving before the end of your last scheduled class"
  • Empleado NO flexible intenta salir antes del final de su última clase. Tolerancia: 5 minutos (Europe/Madrid + DST).

Errores de negocio – CONSULTA FICHAJE ABIERTO (Open)

Origen: GetOpenTimeRecordUseCase

  • EMPLOYEE_ID_REQUIRED
  • HTTP 400
  • message: "Employee ID is required"
  • Falta employeeId en el token.

Variables de entorno

  • GEOFENCE_RADIUS_METERS: radio de la geovalla (m);
  • Zona horaria: Europe/Madrid (manejo automático de horario de verano).