> Índice completo de la documentación: https://trackerintl.com/devs/llms.txt
> Esta página en HTML: https://trackerintl.com/devs/errores
> Estado: Verificado, revisada el 2026-10-05. Verificado por lectura del código y diff contra producción; las formas de error se midieron en un entorno de pruebas. El 429 es inferido del comportamiento estándar y no se midió.

# Errores

Formas de error de la API de la plataforma, qué significa cada código HTTP y cómo reaccionar, incluidos los errores que llegan con HTTP 200.

La API devuelve errores con tres formas distintas. Conocerlas evita que trates como correcta una respuesta que no lo es.

## Formas de error

**Autenticación (`401`)**:

```json
{
  "status": 0,
  "message": "Wrong credentials."
}
```

El texto de `message` se traduce según el idioma de la petición.

**Errores estándar (`403`, `404`, `422`, `500`)**: un objeto con `statusCode` (igual al código HTTP), `message`, `status` en `0`, y, cuando aplica, `errors` con un arreglo de mensajes por campo. En los `403` llega además `perm` en `0`.

**Validación del inicio de sesión (`422`)**: sin `statusCode`:

```json
{
  "status": 0,
  "errors": {
    "email": ["The Email field is required."],
    "password": ["The Password field is required."]
  }
}
```

**Errores con HTTP 200**: algunas validaciones, por ejemplo `point_in_geofences` sin `lat` o `lng`, responden `200` con `{"status": 0, "errors": {...}}`. Revisa siempre `status`, no solo el código HTTP.

## Códigos y cómo reaccionar

| Código | Significado | Qué hacer |
|---|---|---|
| `200` con `status` en `0` | Validación fallida con HTTP 200 | Corrige los parámetros que indica `errors` |
| `401` | Hash ausente o incorrecto, usuario inactivo, suscripción vencida o API deshabilitada | Verifica el hash y vuelve a iniciar sesión; si persiste, contacta a quien administra tu cuenta |
| `403` | Sin permiso del rol para el módulo, vehículo de otro usuario o cuenta restringida por facturación | Revisa tus permisos con `get_user_data`; usa solo `id` de vehículos que te devolvió tu propia lista |
| `404` | Recurso inexistente (vehículo, o usuario sin geocercas en las consultas de geocercas) | Verifica el `id` |
| `422` | Faltan parámetros, formato de hora inválido, rango mayor de 31 días en `get_history` o vehículo vencido | Corrige la petición |
| `429` | Límite de peticiones superado (inferido; no medido) | Espera y reintenta con retroceso exponencial. Mira [Límites](/devs/limites) |
| `500` | Error interno; el mensaje es genérico | Reintenta una vez; si persiste, contacta a soporte |

## Un caso conocido de `500`

En un entorno de pruebas, `get_devices` y `get_devices_latest` fallaron con `500` cuando algún vehículo de la cuenta tenía el icono sin asignar. No sabemos cuántos vehículos de producción están en ese caso. Si recibes un `500` constante en esas dos operaciones, avisa a quien administra tu cuenta.

## Buenas prácticas

- Registra el código HTTP, el `message` y la ruta, pero **nunca** el hash.
- Reintenta solo errores `429` y `5xx`, con espera creciente. No reintentes `401`, `403`, `404` ni `422` sin cambiar algo.
- Trata `403` y `404` como datos: pueden significar "este usuario no tiene acceso", no "la API falló".