Conceptos
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.
Estado: Verificado · Revisada el 5 de octubre de 2026
Qué se verificó y cómo: 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ó.
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):
{
"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:
{
"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 |
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
messagey la ruta, pero nunca el hash. - Reintenta solo errores
429y5xx, con espera creciente. No reintentes401,403,404ni422sin cambiar algo. - Trata
403y404como datos: pueden significar "este usuario no tiene acceso", no "la API falló".