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" }
  ]
}
CampoDescripción
typeTipo de error, o about:blank
titleResumen breve, como la frase de estado HTTP
statusEl código de estado HTTP
detailExplicación legible para humanos de este error
instanceLa ruta de la solicitud
errorsErrores de validación a nivel de campo, cada uno con field, index y message (solo 400)
codeUn 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.
retryabletrue 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ódigoDescripción
400Parámetros de solicitud inválidos o cuerpo de solicitud malformado
401Clave API faltante o inválida
403La clave API no tiene los permisos requeridos para este endpoint
404El recurso solicitado no existe
429Límite de velocidad excedido - reintenta después del tiempo especificado
500Error interno del servidor - contacta soporte si persiste
503Servicio 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.

202Resultado desconocido. No reenviar. Consulte primero el historial de comandos.
500Error 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.
503No enviado. Es seguro reintentar.
502El proveedor rechazó el comando. Reintente solo si retryable es true.
409El dispositivo no puede aceptar este comando. Los reintentos fallarán hasta que cambie su estado.
422El 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
}

Referencia completa de comandos de dispositivos

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)

Elija su horario

Cargando...
Abrir el calendario de reservas