Обработка ошибок для API Excel

В этой статье приводятся общие инструкции и рекомендации по обработке ошибок, возвращаемых API Excel в Microsoft Graph при сбое запроса, отправленного через API.

Типы ответов на ошибки

API Excel в Microsoft Graph возвращают два типа ошибок. Один из них — это обычный ответ об ошибке, который выглядит следующим образом.

HTTP/1.1 <HTTP status code>
Content-type: application/json
Retry-After: <Cooldown duration in seconds> (optional)

{
  "error": <Error object>
}

Второй — из шаблона длительных операций, который может возвращать 200 OK код состояния HTTP и failed состояние операции в тексте ответа, как показано в следующем примере.

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

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

Для обоих этих ответов на ошибки объект error имеет следующую структуру.

Примечание.

Сообщения об ошибках соответствуют определению в спецификации OData версии 4.

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

Объект innerError может рекурсивно содержать больше объектов innerError с дополнительными, более конкретными кодами ошибок. Например, объект error может содержать более подробные сведения об ошибке в коде ошибки второго уровня и сообщении, как показано ниже.

{
  "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" }
  }
}

Действия по обработке ответов об ошибках

Ожидается, что клиенты Microsoft Graph будут использовать следующие действия для обработки ошибок, возникающих с API Excel.

1. Определите, является ли это ошибкой длительной операции

Прежде чем обрабатывать ошибку, сначала необходимо определить, является ли ответ на ошибку шаблоном длительной операции или регулярным шаблоном. Долго выполняющаяся ошибка операции вернет 200 OK код состояния HTTP и failed состояние операции в тексте ответа. Обычный ответ об ошибке возвращает соответствующий код состояния ошибки HTTP.

2. Анализ кода ошибки второго уровня

Клиент должен сначала проанализировать требуемые коды ошибок второго уровня и обработать их в соответствии с инструкциями. При необходимости клиент также может обрабатывать другие коды ошибок второго уровня или использовать коды ошибок верхнего уровня или коды состояния.

Коды ошибок не учитывают регистр.

Обязательные коды ошибок второго уровня

В следующей таблице перечислены инструкции для обязательных кодов ошибок второго уровня, которые должны обрабатывать клиенты Microsoft Graph. Служба может добавить новые коды ошибок в любое время.

Код	Инструкции
accessConflict	Неудачный запрос конфликтует с другими клиентами, обращаюющимися к книге (например, другой клиент заблокировал книгу для редактирования). Клиент Microsoft Graph не должен повторно отправлять неудачный запрос, пока конфликт не будет разрешен. Пользователь может вручную выполнить те же операции в Excel Online, чтобы получить дополнительные сведения о конфликте.
badRequestUncategorized	В неудачном запросе обнаружена неуказаная ошибка. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
conflictUncategorized	Неудачный запрос конфликтует с определенным состоянием сервера. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос, пока конфликт не будет разрешен. Пользователь может вручную выполнить те же операции в Excel Online, чтобы получить дополнительные сведения о конфликте.
forbiddenUncategorized	Неудачный запрос запрещен. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос. Пользователь может вручную выполнить те же операции в Excel Online, чтобы получить дополнительные сведения об ограничениях.
gatewayTimeoutUncategorized	Служба не смогла выполнить запрос в течение ограниченного времени.
internalServerErrorUncategorized	Произошла неуказанная ошибка. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос. Если сеанс указан в неудачном запросе, дальнейший доступ к сеансу также не ожидается.
invalidSessionAccessConflict	Сеанс, указанный в запросе, недопустим из-за конфликтов с другими клиентами, которые обращаются к книге (например, другой клиент заблокировал книгу для редактирования). Дальнейший доступ к сеансу, указанному в неудачном запросе, не ожидается. Повторное создание сеансов с тем же запросом createSession не ожидается, пока конфликт не будет разрешен. Повторное создание сеансов с другим запросом createSession может завершиться ошибкой. Пользователь может вручную выполнить те же операции в Excel Online, чтобы получить дополнительные сведения о конфликте.
invalidSessionAuthentication	Сеанс, указанный в запросе, недопустим из-за ошибки проверки подлинности. Дальнейший доступ к сеансу, указанному в неудачном запросе, не ожидается. Повторное создание сеансов с тем же запросом createSession не ожидается, пока не будут предоставлены соответствующие сведения о проверке подлинности.
invalidSessionNotFound	Сеанс, указанный в запросе, недопустим, так как не удается найти книгу. Дальнейший доступ к сеансу, указанному в неудачном запросе, не ожидается. Повторное создание сеансов с тем же запросом createSession не ожидается.
invalidSessionReCreatable	Сеанс, указанный в запросе, не существует или недопустим из-за временной ошибки. Клиент Microsoft Graph может попытаться воссоздать сеанс и возобновить работу. Дальнейший доступ к сеансу, указанному в неудачном запросе, не ожидается.
invalidSessionRestricted	Сеанс, указанный в запросе, недопустим из-за конфигураций службы или ограничений. Дальнейший доступ к сеансу, указанному в неудачном запросе, не ожидается. Повторное создание сеансов с тем же запросом createSession не ожидается до изменения ограничений или конфигураций, блокирующих запрос. Повторное создание сеансов с другим запросом createSession может завершиться ошибкой. Пользователь может вручную выполнить те же операции в Excel Online, чтобы получить дополнительные сведения об ограничениях.
invalidSessionUnexpected	Сеанс, указанный в запросе, недопустим из-за непредвиденной проблемы. Дальнейший доступ к сеансу, указанному в неудачном запросе, не ожидается. Повторное создание сеансов с тем же запросом createSession не ожидается. Повторное создание сеансов с другим запросом createSession может завершиться ошибкой.
invalidSessionUnsupportedWorkbook	Сеанс, указанный в запросе, недопустим, так как книга содержит неподдерживаемые функции или превышает ограничение на размер. Как правило, неподдерживаемые факторы вводятся другим клиентом, обращаюющимся к книге. Дальнейший доступ к сеансу, указанному в неудачном запросе, не ожидается. Повторное создание сеансов с тем же запросом createSession не ожидается, пока не будут удалены неподдерживаемые факторы. Повторное создание сеансов с другим запросом createSession может завершиться ошибкой. Пользователь может вручную выполнить те же операции в Excel Online, чтобы получить дополнительные сведения о неподдерживаемых факторах, или в классическом приложении Excel, где может поддерживаться книга.
methodNotAllowedUncategorized	Метод HTTP, указанный в запросе, не разрешен для ресурса. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
notFoundUncategorized	Не удается найти запрошенный ресурс. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
notImplementedUncategorized	Запрошенная функция в настоящее время не реализована. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
payloadTooLargeUncategorized	Полезные данные запроса превышают предельный размер. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
serviceUnavailableUncategorized	Служба временно недоступна или перегружена. Ожидается, что клиент Microsoft Graph не будет повторно отправлять неудачный запрос до тех пор, пока не пройдет указанная длительность cooldown.
tooManyRequestsUncategorized	Сбой запроса превышает определенное ограничение частоты. Ожидается, что клиент Microsoft Graph не будет повторно отправлять неудачный запрос до тех пор, пока не пройдет указанная длительность cooldown. Рекомендации по сокращению регулирования см. в статье Уменьшение ошибок регулирования.
transientFailure	Сбой запроса из-за временной ошибки. Ожидается, что клиент Microsoft Graph не будет повторно отправлять неудачный запрос до тех пор, пока не пройдет указанная длительность cooldown.
unauthorizedUncategorized	Необходимые сведения о проверке подлинности для ресурса либо отсутствуют, либо недопустимы. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
unsupportedWorkbook	Сбой запроса. Книга содержит неподдерживаемые функции или превышает ограничение на размер. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос до тех пор, пока не будут удалены неподдерживаемые факторы.

Примечание.

Для обычного шаблона неудачный запрос определяется как запрос, соответствующий ответу. Для шаблона длительных операций сбойный запрос является тем, который активирует неудачную операцию.

Необязательные примеры кода ошибки второго уровня

В следующей таблице приведены примеры необязательных кодов ошибок второго уровня, включая соответствующие инструкции по обработке для каждого кода ошибки. Служба может добавить новые коды ошибок в любое время.

Код	Инструкции
accessDenied	Вы не можете выполнить запрошенную операцию (например, изменение заблокированных ячеек). Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
filteredRangeConflict	Сбой операции, так как она конфликтует с отфильтрованным диапазоном. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
generalException	Во время обработки запроса произошла внутренняя ошибка. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
insertDeleteConflict	Операция вставки или удаления привела к конфликту. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос. Пользователь может вручную выполнить те же операции в Excel Online, чтобы получить дополнительные сведения о конфликте.
invalidArgument	Аргумент недопустим, отсутствует или имеет неправильный формат. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
invalidReference	Эта ссылка недопустима для текущей операции. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
itemAlreadyExists	Создаваемый ресурс уже существует. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
itemNotFound	Запрашиваемый ресурс не существует. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
methodNotAllowed	Метод HTTP, указанный в запросе, не разрешен для ресурса. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
nonBlankCellOffSheet	Не удается вставить новые ячейки, так как это приведет к отправке непустых ячеек с конца листа. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос. Пользователь может удалить строки или столбцы, чтобы освободить место для вставки содержимого, а затем повторить попытку.
rangeExceedsLimit	Число ячеек в диапазоне превысило максимальное поддерживаемого числа. Клиент Microsoft Graph может попытаться отправить запрос с меньшим размером диапазона. Дополнительные сведения см. в разделе Ограничения ресурсов и оптимизация производительности для надстроек Office.
requestAborted	Запрос был прерван во время выполнения, что обычно было вызвано длительным вычислением из функций в книге. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.
unsupportedOperation	Выполняемая операция не поддерживается. Клиент Microsoft Graph не должен повторно отправлять неудачный запрос.

Примечание.

Для обычного шаблона неудачный запрос определяется как запрос, соответствующий ответу. Для шаблона длительных операций сбойный запрос является тем, который активирует неудачную операцию.

3. Анализ кода ошибки верхнего уровня

Если вы не можете найти известный код ошибки второго уровня, следуйте инструкциям, приведенным для ошибок верхнего уровня. Коды ошибок верхнего уровня привязаны к коду состояния, и вы можете выполнить действия в соответствии с соответствующими кодами состояния. Дополнительные сведения о кодах ошибок и сообщениях верхнего уровня см. в разделе Коды ошибок и сообщения.

4. Анализ кода состояния

Если в обычном шаблоне не удалось найти известный код ошибки второго уровня или код ошибки верхнего уровня, следует выполнить действия в соответствии с кодом состояния HTTP.

5. Ошибка при восстановлении

Для некоторых ответов в обычном шаблоне длительность восстановления в секундах может быть предоставлена с помощью заголовка Retry-After . При наличии длительности восстановления для восстановления клиент Microsoft Graph не должен отправлять запросы на выполнение до истечения указанной длительности. Рекомендации по управлению Retry-After заголовками и регулированием см. в статье Уменьшение ошибок регулирования.

Диагностические сведения

Все содержимое в ответе, которое не использовалось на предыдущих шагах, предназначено только для диагностика целей (включая строки в полях сообщения). Не рекомендуется полагаться на это содержимое, так как оно может измениться без уведомления.

Обработка особых случаев

При возникновении ошибки или 503/serviceUnavailable при обнаружении известного 502/badGateway кода ошибки второго уровня при выполнении сеансовых запросов следуйте соответствующим инструкциям; в противном случае следует напрямую воссоздать сеанс.

Связанные материалы

• Использование REST API для Excel