Control de errores para las API de Excel

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

Las API de Excel en 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
Retry-After: <Cooldown duration in seconds> (optional)

{
  "error": <Error object>
}

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

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

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

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

Nota:

Las respuestas de error siguen la definición en la especificación OData v4 de las respuestas de error.

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

El objeto innerError podría contener de forma recursiva más objetos innerError con códigos de error adicionales más específicos. Por ejemplo, el objeto de error podría contener información de error más detallada en el código y el mensaje 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

Se espera que los clientes de Microsoft Graph usen los pasos siguientes para controlar los errores que se producen con las API de Excel.

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

Antes de controlar un error, el primer paso consiste en determinar si la respuesta del error procede de un patrón de operación de ejecución prolongada o de un patrón normal. Un error de operación de ejecución prolongada devolverá un código de estado HTTP y failed un 200 OK estado de operación en el cuerpo de la respuesta. Una respuesta de error normal 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 ejecución prolongada como para el patrón normal, el cliente primero debe analizar los códigos de error de segundo nivel necesarios y controlarlos según las instrucciones. Opcionalmente, el cliente también puede controlar otros códigos de error de segundo nivel o optar por volver a códigos de error o códigos de estado de nivel superior.

Los códigos de error no distinguen mayúsculas de minúsculas.

Códigos de error de segundo nivel necesarios

En la tabla siguiente se enumeran las instrucciones para los códigos de error de segundo nivel necesarios que se espera que controlen los clientes de Microsoft Graph. 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 acceden al libro (por ejemplo, otro cliente ha bloqueado el libro para su edición). No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores hasta que se resuelva el conflicto. Un usuario final puede optar por realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre el conflicto.
badRequestUncategorized	Se encuentra un error no especificado en la solicitud con error. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
conflictUncategorized	La solicitud con error entra en conflicto con cierto estado de servidor. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores hasta que se resuelva el conflicto. Un usuario final puede optar por realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre el conflicto.
forbiddenUncategorized	No se permite la solicitud con errores. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores. Un usuario final puede optar por 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.
internalServerErrorUncategorized	Se ha producido un error no especificado. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores. Si se especifica una sesión en la solicitud con error, tampoco se espera más acceso a la sesión.
invalidSessionAccessConflict	La sesión especificada en la solicitud no es válida debido a conflictos con otros clientes que acceden al libro (por ejemplo, otro cliente ha bloqueado el libro para su edición). No se espera más acceso 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 podría o no realizarse correctamente. Un usuario final puede optar por 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 más acceso 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 proporcione 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 más acceso 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 de Microsoft Graph puede intentar volver a crear una sesión y reanudar el trabajo. No se espera más acceso 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 más acceso 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 podría o no realizarse correctamente. Un usuario final puede optar por 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 más acceso 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 podría o no realizarse correctamente.
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 introduce los factores no admitidos. No se espera más acceso 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 podría o no realizarse correctamente. Un usuario final puede optar por realizar manualmente las mismas operaciones con Excel Online para obtener más detalles de los factores no admitidos, o con Excel Desktop donde podría admitirse el libro.
methodNotAllowedUncategorized	No se permite el método HTTP especificado en la solicitud en el recurso. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
notFoundUncategorized	No se encuentra el recurso solicitado. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
notImplementedUncategorized	La característica solicitada no está implementada actualmente. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
payloadTooLargeUncategorized	La carga de la solicitud supera el límite de tamaño. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
serviceUnavailableUncategorized	El servicio no está disponible temporalmente o está sobrecargado. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores hasta que pase la duración de tiempo de reutilización especificada.
tooManyRequestsUncategorized	La solicitud con error supera cierta limitación de frecuencia. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores hasta que pase la duración de tiempo de reutilización especificada. Para conocer los procedimientos recomendados para reducir la limitación, consulte Reducción de errores de limitación.
transientFailure	Error en la solicitud debido a un error transitorio. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores hasta que pase la duración de tiempo de reutilización especificada.
unauthorizedUncategorized	Falta información de autenticación necesaria para el recurso o no es válida. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
unsupportedWorkbook	Error en la solicitud. El libro contiene características no admitidas o supera el límite de tamaño. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores hasta que se quiten los factores no admitidos.

Nota:

Para el patrón normal, la solicitud con error se define como la solicitud que corresponde a la respuesta. Para el patrón de operación de ejecución prolongada, la solicitud con error es la que desencadena la operación con errores.

Ejemplos opcionales de código de error de segundo nivel

En la tabla siguiente se enumeran ejemplos de códigos de error opcionales de segundo nivel, incluidas las instrucciones de control correspondientes para cada código de error. El servicio puede agregar nuevos códigos de error en cualquier momento.

Código	Instrucciones
accessDenied	No se puede realizar la operación solicitada (por ejemplo, realizar cambios en celdas bloqueadas). No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
filteredRangeConflict	Error en la operación porque entra en conflicto con un intervalo filtrado. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
generalException	Error interno al procesar la solicitud. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
insertDeleteConflict	La operación de inserción o eliminación intentada dio lugar a un conflicto. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores. Un usuario final puede optar por realizar manualmente las mismas operaciones con Excel Online para obtener más detalles sobre el conflicto.
invalidArgument	El argumento no es válido, falta o tiene un formato incorrecto. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
invalidReference	Esta referencia no es válida para la operación actual. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
itemAlreadyExists	El recurso que se está creando ya existe. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
itemNotFound	El recurso solicitado no existe. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
methodNotAllowed	No se permite el método HTTP especificado en la solicitud en el recurso. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
nonBlankCellOffSheet	No se pueden insertar nuevas celdas porque insertaría celdas no vacías fuera del final de la hoja de cálculo. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores. Un usuario final puede eliminar filas o columnas para dejar espacio al contenido que se va a insertar y, a continuación, volver a intentarlo.
rangeExceedsLimit	El recuento de celdas en el intervalo ha superado el número máximo admitido. El cliente de Microsoft Graph puede intentar enviar una solicitud con un tamaño de intervalo más pequeño. Para obtener más información, vea Límites de recursos y optimización del rendimiento para complementos de Office.
requestAborted	La solicitud se anuló durante el tiempo de ejecución, lo que normalmente se debe al cálculo de largo tiempo de las funciones del libro. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.
unsupportedOperation	No se admite la operación que se está intentando. No se espera que el cliente de Microsoft Graph vuelva a enviar la solicitud con errores.

Nota:

Para el patrón normal, la solicitud con error se define como la solicitud que corresponde a la respuesta. Para el patrón de operación de ejecución prolongada, la solicitud con error es la que desencadena la operación con errores.

3. Análisis del código de error de nivel superior

Si no encuentra ningún código de error conocido de segundo nivel, debe seguir 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 según los códigos de estado correspondientes. Para obtener más información sobre los mensajes y códigos de error de nivel superior, consulte Códigos de error y mensajes.

4. Análisis del código de estado

Para el patrón normal, si no pudo encontrar ningún código de error de segundo nivel conocido o código de error de nivel superior, debe realizar una acción según el código de estado HTTP.

5. Tiempo de reutilización de recuperación de errores

Para algunas de las respuestas del patrón normal, es posible que se proporcione una duración de tiempo de reutilización de recuperación en segundos a través de un Retry-After encabezado. Cuando hay una duración de tiempo de reutilizació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. Para conocer los procedimientos recomendados relacionados con el Retry-After encabezado y la limitación, consulte Reducción de errores de limitación.

Información de diagnóstico

Todo el contenido de la respuesta que no se usa en los pasos anteriores es solo para fines de diagnóstico (incluidas las cadenas en los campos de mensaje ). No se recomienda que tome una dependencia de estos contenidos, ya que podrían cambiar sin previo aviso.

Control especial de casos

En el caso de las solicitudes con sesión, si encuentra un 502/badGateway error o 503/serviceUnavailable , cuando se encuentra un código de error de segundo nivel conocido, siga las instrucciones correspondientes; de lo contrario, debe volver a crear la sesión directamente.

Contenido relacionado

• Usar la API de REST de Excel