Manejo de Errores
La API usa códigos de respuesta HTTP convencionales para indicar el éxito o fracaso de las solicitudes. Esta página documenta formatos de error y estrategias de manejo.
Formatos de respuesta de error
El formato depende del lugar donde se produzca el error.
Errores de autenticación y de límite de velocidad (401 y 429)
Un objeto JSON pequeño con error, message y status. Los endpoints de cambio de políticas, el endpoint de código QR de aprovisionamiento y los endpoints de comandos de dispositivos que no sean lock, lost-mode, found y message, son la excepción: su 429 utiliza el formato de detalle del problema (problem details) que se indica a continuación, con code y retryable.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{
"error": "Too Many Requests",
"message": "Rate limit exceeded for device commands on this API key. Try again later.",
"status": 429
} Todos los demás errores (por ejemplo, 400, 403, 409, 422, 500, 502 y 503)
Detalle del problema según RFC 9457 con el tipo de contenido application/problem+json. Los errores de validación añaden un array errors. Los endpoints de cambio de políticas, el endpoint de código QR de aprovisionamiento y los endpoints de comandos de dispositivos que no sean lock, lost-mode, found y message añaden un miembro code a cada error excepto al 401. En el endpoint de código QR de aprovisionamiento, un cuerpo que no sea JSON válido o que tenga un campo desconocido también es una excepción: su 400 no tiene code. El miembro retryable se describe a continuación.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "VALIDATION_ERROR",
"title": "Validation Error",
"status": 400,
"instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
"errors": [
{ "field": "title", "index": null, "message": "must not be blank" }
]
} | Campo | Descripción |
|---|---|
| type | Tipo de error, o about:blank |
| title | Resumen breve, como la frase de estado HTTP |
| status | El código de estado HTTP |
| detail | Explicación legible para humanos de este error |
| instance | La ruta de la solicitud |
| errors | Errores de validación a nivel de campo, cada uno con field, index y message (solo 400) |
| code | Un código de error estable para bifurcar lógica, como not_found, forbidden o internal_error. Enviado por los endpoints de cambio de políticas, el endpoint de código QR de aprovisionamiento y los endpoints de comandos de dispositivo distintos de lock, lost-mode, found y message. |
| retryable | true si se puede reintentar la misma solicitud. Se envía en 502 y 503 desde todos los endpoints de comandos de dispositivos, en 429 y 500 desde los endpoints de comandos que no sean lock, lost-mode, found y message, y en cada error que incluya un code desde los endpoints de cambio de políticas y el endpoint de código QR de aprovisionamiento. |
Un 404 para un activo o una política desconocidos tiene el cuerpo vacío. Los endpoints de cambio de políticas, el endpoint de código QR de aprovisionamiento y los endpoints de comandos de dispositivos que no sean lock, lost-mode, found y message son la excepción: su 404 es un detalle del problema con code not_found.
Los endpoints de sesión de Device User responden 400, 404 y 409 con application/problem+json y un miembro code para bifurcar; no envían ningún miembro retryable. Dos excepciones no tienen code: 401 y 403, y un 400 por un parámetro de consulta no válido de GET /device-user-logins. API de sesiones de usuarios de dispositivos
Códigos de Estado HTTP
| Código | Descripción |
|---|---|
| 400 | Parámetros de solicitud inválidos o cuerpo de solicitud malformado |
| 401 | Clave API faltante o inválida |
| 403 | La clave API no tiene los permisos requeridos para este endpoint |
| 404 | El recurso solicitado no existe |
| 429 | Límite de velocidad excedido - reintenta después del tiempo especificado |
| 500 | Error interno del servidor - contacta soporte si persiste |
| 503 | Servicio temporalmente no disponible - intenta de nuevo más tarde |
Respuestas a comandos de dispositivos
Los puntos de conexión de comandos utilizan códigos de estado con reglas especiales de reintento. Reintentar el incorrecto puede enviar un comando a un dispositivo dos veces.
| 202 | Resultado desconocido. No reenviar. Consulte primero el historial de comandos. |
|---|---|
| 500 | Error inesperado, con código internal_error fuera de los endpoints lock, lost-mode, found y message. Se desconoce si el comando llegó al dispositivo. Compruebe el dispositivo antes de reintentar. |
| 503 | No enviado. Es seguro reintentar. |
| 502 | El proveedor rechazó el comando. Reintente solo si retryable es true. |
| 409 | El dispositivo no puede aceptar este comando. Los reintentos fallarán hasta que cambie su estado. |
| 422 | El proveedor denegó el comando. No reintente con los mismos argumentos. |
HTTP/1.1 202 Accepted
{
"assetId": "k3x9m2pa",
"type": "LOCK",
"status": "UNCONFIRMED",
"detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
} HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Service Unavailable",
"status": 503,
"detail": "Command was not sent; it is safe to retry.",
"instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
"retryable": true
} Estrategia de Reintento
Reintente solo cuando sea seguro. Las solicitudes de lectura que fallen con un error transitorio se pueden reintentar con un retroceso exponencial (exponential backoff). Un comando de dispositivo debe seguir las reglas de la sección de respuestas a comandos de dispositivos. Después de un error en un cambio de política o en un código QR de aprovisionamiento, siga su campo retryable, y tras un error inesperado al aplicar (apply), lea la propuesta antes de volver a proponer.
- Para errores 429, espere el número de segundos indicado en el encabezado Retry-After antes de reintentar.
- Para errores 5xx en solicitudes de lectura, use un retroceso exponencial (1s, 2s, 4s, 8s...) con fluctuación aleatoria (jitter). Para comandos de dispositivos, reintente solo un 503 (no enviado) o un 502 con retryable establecido en true. Después de un 202 o un 500, compruebe el dispositivo antes de volver a enviar.
- Establece un conteo máximo de reintentos (ej. 3-5 intentos) para evitar bucles infinitos
Limitación de Velocidad
Cuando supera el límite de solicitudes de MCP, o llama al endpoint lock, lost-mode, found o message superando el límite de comandos, la API devuelve HTTP 429 Too Many Requests con un encabezado Retry-After y un cuerpo JSON con error, message y status. Los demás endpoints de comandos de dispositivos, los endpoints de cambio de políticas y el endpoint de código QR de aprovisionamiento también envían Retry-After al superar el mismo límite, pero su cuerpo es un detalle del problema con code rate_limited y retryable true. Cuando una llamada de comando MCP, cambio de política o herramienta de aprovisionamiento supera el límite de comandos, el resultado es un error de herramienta cuyo texto indica cuántos segundos esperar.
Utilice el encabezado Retry-After, o los segundos indicados en un error de la herramienta, para decidir cuándo reintentar. La API no envía los encabezados X-RateLimit-Limit, X-RateLimit-Remaining ni X-RateLimit-Reset.
Errores de Validación
Para errores 400 causados por un cuerpo de solicitud no válido, el detalle del problema incluye un array errors con una entrada por cada campo no válido. Otros errores 400, como un valor lastSeenBefore no válido, explican el problema en detalle.
Mejores Prácticas de Manejo de Errores
- Siempre verifica el código de estado HTTP antes de parsear el cuerpo de la respuesta
- Siga el encabezado Retry-After en errores 429, y use retroceso exponencial para errores 5xx en solicitudes de lectura. Para comandos de dispositivos, reintente solo un 503 o un 502 con retryable establecido en true, y nunca reenvíe tras un 202 o un 500 sin comprobar primero el dispositivo.
- Registre el estado HTTP y el detail o message del cuerpo del error para depuración. Los cuerpos de error no incluyen campos de marca de tiempo (timestamp) ni de ruta (path).
- Maneja códigos de error específicos de manera diferente (ej. 401 activa re-autenticación)