> ## Documentation Index
> Fetch the complete documentation index at: https://atlas-1d44e232.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de error

> Contrato del body de error de la API y catálogo de códigos estables.

Toda respuesta de error de la API tiene este shape:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

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