Control de errores para Excel API de Microsoft Graph

En este artículo se proporcionan instrucciones generales y sugerencias para controlar los errores devueltos por las API de Excel en Microsoft Graph cuando se produce un error en una solicitud enviada a través de la API.

Tipos de respuestas de error

Excel Las API de Microsoft Graph devuelven dos tipos de errores. Una es la respuesta de error normal, que es similar a la siguiente.

HTTP/1.1 <HTTP status code>
Content-type: application/json

{
  "error": <Error object>
}

El segundo es del patrón de operación de larga ejecución, que puede devolver un código de estado HTTP y el estado de la operación en el cuerpo de la respuesta, como 200 OK en el ejemplo failed siguiente.

HTTP/1.1 200 OK
Content-type: application/json

{
  "status": "failed",
  "error": <Error object>
}

Para ambas respuestas de error, el objeto de error tiene la siguiente estructura.

Nota: Las respuestas de error siguen la definición de la especificación de OData v4 para respuestas de error.

{
  "code": "string",
  "message": "string",
  "innerError": { "@odata.type": "odata.error" }
}

El objeto innerError puede contener de forma recursiva más objetos innerError con códigos de error adicionales y más concretos. Por ejemplo, el objeto de error puede contener información de error más detallada en el mensaje y el código de error de segundo nivel, como se muestra.

{
  "code": "Top-level error code",
  "message": "Top-level error message",
  "innerError": {
    "code": "Second-level error code",
    "message": "Second-level error message",
    "innerError": { "@odata.type": "odata.error" }
  }
}

Pasos para controlar las respuestas de error

Los Graph microsoft pueden usar los siguientes pasos para controlar los errores que se producen con Excel API.

1. Determinar si se trata de un error de operación de larga ejecución

Antes de controlar un error, el primer paso consiste en determinar si la respuesta al error es de un patrón de operación de larga ejecución o de un patrón normal. Un error de operación de larga ejecución devolverá un código de estado HTTP y 200 OK el estado de la operación en el cuerpo de la failed respuesta. Una respuesta de error regular devolverá un código de estado de error HTTP correspondiente.

2. Analizar código de error de segundo nivel

Tanto para el patrón de operación de larga ejecución como para el patrón normal, se recomienda seguir primero las instrucciones para los errores de segundo nivel. El código de error no tiene mayúsculas de minúsculas. En la tabla siguiente se enumeran las instrucciones para algunos de los errores. El servicio puede agregar nuevos códigos de error en cualquier momento.

Código Instrucciones
accessConflict La solicitud con error entra en conflicto con otros clientes que tienen acceso al libro (por ejemplo, otro cliente ha bloqueado el libro para su edición). No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error hasta que se resuelva el conflicto. Un usuario final puede elegir realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre el conflicto.
accessDenied No puede realizar la operación solicitada (por ejemplo, realizar cambios en las celdas bloqueadas). No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
badRequestUncategorized Se encuentra un error no especificado en la solicitud con error. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
conflictUncategorized La solicitud con error entra en conflicto con determinado estado del servidor. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error hasta que se resuelva el conflicto. Un usuario final puede elegir realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre el conflicto.
filteredRangeConflict Error en la operación porque entra en conflicto con un intervalo filtrado. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
forbiddenUncategorized No se permite la solicitud con error. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error. Un usuario final puede elegir realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre las restricciones.
gatewayTimeoutUncategorized El servicio no pudo completar la solicitud dentro del límite de tiempo.
generalException Se produjo un error interno al procesar la solicitud. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
insertDeleteConflict La operación de inserción o eliminación intentada dio lugar a un conflicto. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error. Un usuario final puede elegir realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre el conflicto.
internalServerErrorUncategorized Se ha producido un error no especificado. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error. Si se especifica una sesión en la solicitud con error, tampoco se espera un acceso adicional a la sesión.
invalidArgument El argumento no es válido, o falta o tiene un formato incorrecto. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
invalidReference Esta referencia no es válida para la operación actual. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
invalidSessionAccessConflict La sesión especificada en la solicitud no es válida debido a conflictos con otros clientes que tienen acceso al libro (por ejemplo, otro cliente ha bloqueado el libro para su edición). No se espera un acceso adicional a la sesión especificada en la solicitud con error. No se espera volver a crear sesiones con la misma solicitud createSession hasta que se resuelva el conflicto. La recreación de sesiones con una solicitud createSession diferente puede o no ser correcta. Un usuario final puede elegir realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre el conflicto.
invalidSessionAuthentication La sesión especificada en la solicitud no es válida debido a un error de autenticación. No se espera un acceso adicional a la sesión especificada en la solicitud con error. No se espera volver a crear sesiones con la misma solicitud createSession hasta que se proporciona la información de autenticación adecuada.
invalidSessionNotFound La sesión especificada en la solicitud no es válida porque no se encuentra el libro. No se espera un acceso adicional a la sesión especificada en la solicitud con error. No se espera volver a crear sesiones con la misma solicitud createSession.
invalidSessionReCreatable La sesión especificada en la solicitud no existe o no es válida debido a un error transitorio. El cliente Graph microsoft puede intentar volver a crear una sesión y reanudar el trabajo. No se espera un acceso adicional a la sesión especificada en la solicitud con error.
invalidSessionRestricted La sesión especificada en la solicitud no es válida debido a las configuraciones o restricciones del servicio. No se espera un acceso adicional a la sesión especificada en la solicitud con error. No se espera volver a crear sesiones con la misma solicitud createSession hasta que cambien las restricciones o configuraciones que bloquean la solicitud. La recreación de sesiones con una solicitud createSession diferente puede o no ser correcta. Un usuario final puede elegir realizar manualmente las mismas operaciones con Excel Online para obtener más detalles de las restricciones.
invalidSessionUnexpected La sesión especificada en la solicitud no es válida debido a un problema inesperado. No se espera un acceso adicional a la sesión especificada en la solicitud con error. No se espera volver a crear sesiones con la misma solicitud createSession. La recreación de sesiones con una solicitud createSession diferente puede o no ser correcta.
invalidSessionUnsupportedWorkbook La sesión especificada en la solicitud no es válida porque el libro contiene características no admitidas o supera el límite de tamaño. Normalmente, otro cliente que accede al libro presenta los factores no admitidos. No se espera un acceso adicional a la sesión especificada en la solicitud con error. No se espera volver a crear sesiones con la misma solicitud createSession hasta que se quiten los factores no admitidos. La recreación de sesiones con una solicitud createSession diferente puede o no ser correcta. Un usuario final puede elegir realizar manualmente las mismas operaciones con Excel Online para obtener más detalles de los factores no admitidos, o con Excel Desktop donde el libro podría ser compatible.
itemAlreadyExists El recurso que se está creando ya existe. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
itemNotFound El recurso solicitado no existe. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
methodNotAllowed El método HTTP especificado en la solicitud no está permitido en el recurso. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
methodNotAllowedUncategorized El método HTTP especificado en la solicitud no está permitido en el recurso. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
nonBlankCellOffSheet No se pueden insertar nuevas celdas porque se insertarían celdas no vacías fuera del final de la hoja de cálculo. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error. Un usuario final puede eliminar filas o columnas para dar espacio al contenido que se va a insertar y, a continuación, intentarlo de nuevo.
notFoundUncategorized No se puede encontrar el recurso solicitado. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
notImplementedUncategorized La característica solicitada no está implementada actualmente. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
payloadTooLargeUncategorized La carga de la solicitud supera el límite de tamaño. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
rangeExceedsLimit El número de celdas en el intervalo ha superado el número máximo admitido. El cliente Graph microsoft puede intentar enviar una solicitud con un tamaño de intervalo menor. Para obtener más información, vea límites derecursos y optimización de rendimiento para Office complementos .
requestAborted La solicitud se abortó durante el tiempo de ejecución, lo que normalmente se debe al cálculo de tiempo largo de las funciones del libro. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
serviceUnavailableUncategorized El servicio no está disponible temporalmente o está sobrecargado. No se Graph que el cliente de Microsoft vuelva a enviar la solicitud con error hasta que pase la duración del tiempo de reutilización especificado.
tooManyRequestsUncategorized La solicitud con error supera cierta limitación de frecuencia. No se Graph que el cliente de Microsoft vuelva a enviar la solicitud con error hasta que pase la duración del tiempo de reutilización especificado.
transientFailure Error en la solicitud debido a un error transitorio. No se Graph que el cliente de Microsoft vuelva a enviar la solicitud con error hasta que pase la duración del tiempo de reutilización especificado.
unauthorizedUncategorized Falta la información de autenticación necesaria para el recurso o no es válida. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
unsupportedOperation No se admite la operación que se está intentando. No se espera Graph cliente de Microsoft vuelva a enviar la solicitud con error.
unsupportedWorkbook Error en la solicitud. El libro contiene características no admitidas o supera el límite de tamaño. No se Graph que el cliente de Microsoft vuelva a enviar la solicitud con error hasta que se quiten los factores no admitidos.

Nota: Para el patrón normal, la solicitud con error se define como la solicitud correspondiente a la respuesta. Para el patrón de operación de larga ejecución, la solicitud con error es la que desencadena la operación con error.

3. Analizar el código de error de nivel superior

Si no encuentra el código de error de segundo nivel que aparece en el tema Códigos de error detallados, le recomendamos que siga las instrucciones proporcionadas para los errores de nivel superior. Los códigos de error de nivel superior están enlazados al código de estado y puede realizar acciones de acuerdo con los códigos de estado correspondientes. Para obtener más información acerca de los mensajes y códigos de error de nivel superior, vea Códigos de error.

4. Analizar el código de estado

Si el código de error que encuentre no está en la lista de segundo nivel o en la lista de nivel superior, se recomienda realizar acciones de acuerdo con el código de estado HTTP.

5. Enfriamiento de recuperación de errores

Para algunas de las respuestas del patrón normal, se puede proporcionar una duración de recuperación de recuperación en segundos a través de un Retry-After encabezado. Cuando hay una duración de recuperación de recuperación, no se espera que el cliente de Microsoft Graph envíe ninguna solicitud de seguimiento antes de que pase la duración especificada.

Control de casos especiales

Para las solicitudes de sesión ,si encuentra un o error, cuando se muestra un código de error de segundo nivel en Códigos de error detallados , analice el código de segundo nivel y siga las instrucciones correspondientes; de lo contrario, se vuelve a confirmar que se vuelve a crear la sesión 502/badGateway 503/serviceUnavailable directamente.