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.