Стандартные отклики и коды ошибок
Для возвращения ошибок в API OneDrive используются стандартные коды состояния HTTP, а также объект ответа с ошибкой JSON. В ответах могут быть возвращены указанные ниже коды состояния HTTP.
| Код состояния | Сообщение о состоянии | Описание |
|---|---|---|
| 400 | Неправильный запрос (Bad Request) | Не удается обработать запрос, так как он имеет неправильный формат или содержит ошибку. |
| 401 | Не авторизован (Unauthorized) | Требуемые сведения о проверке подлинности отсутствуют или недопустимы для ресурса. |
| 403 | Запрещено | Доступ к запрошенному ресурсу запрещен. Возможно, у пользователя недостаточно разрешений. |
| 404 | Не найдено (Not Found) | Запрашиваемый ресурс не существует. |
| 405 | Недопустимый метод (Method Not Allowed) | Метод HTTP в запросе недопустим для ресурса. |
| 406 | Неприемлемо (Not Acceptable) | Эта служба не поддерживает формат, запрошенный в заголовке Accept. |
| 409 | Conflict | Текущее состояние противоречит ожидаемым результатам запроса. Например, может отсутствовать указанная родительская папка. |
| 410 | Отсутствует (Gone) | Запрошенный ресурс недоступен на сервере. |
| 411 | Требуется длина (Length Required) | В запросе нужно указать заголовок Content-Length. |
| 412 | Необходимое условие не выполнено (Precondition Failed) | Необходимое условие, указанное в запросе (например, заголовок If-Match), не соответствует текущему состоянию ресурса. |
| 413 | Слишком большой объект запроса (Request Entity Too Large) | Размер запроса превышает максимальное значение. |
| 415 | Неподдерживаемый тип носителя (Unsupported Media Type) | Тип содержимого запроса имеет формат, который не поддерживает служба. |
| 416 | Запрошенный диапазон невыполним (Requested Range Not Satisfiable) | Указан недопустимый или недоступный диапазон байтов. |
| 422 | Необрабатываемый объект (Unprocessable Entity) | Не удается обработать запрос из-за неправильной семантики. |
| 429 | Слишком много запросов (Too Many Requests) | Количество запросов клиентского приложения отрегулировано, оно сможет повторить запрос по истечении некоторого времени. |
| 500 | Внутренняя ошибка сервера (Internal Server Error) | При обработке запроса возникла внутренняя ошибка сервера. |
| 501 | Не реализовано (Not Implemented) | Запрашиваемая функция не реализована. |
| 503 | Служба недоступна | Служба временно недоступна. Запрос можно повторить через некоторое время. Возможно, существует заголовок Retry-After. |
| 507 | Недостаточно места (Insufficient Storage) | Достигнута максимальная квота хранилища. |
| 509 | Превышено ограничение пропускной способности | Пропускная способность приложения отрегулирована из-за превышения максимально допустимой пропускной способности. Приложение сможет повторить запрос по истечении некоторого времени. |
Ошибка представляет собой один объект JSON, содержащий одно свойство с именем error. Этот объект включает все сведения об ошибке. Вы можете использовать возвращенные сведения вместо полученного кода состояния HTTP или вместе с ним. Вот пример полного текста ошибки JSON.
{
"error": {
"code": "invalidRange",
"message": "Uploaded fragment overlaps with existing data.",
"innererror": {
"code": "fragmentOverlap"
}
}
}
Свойство code
Свойство code содержит одно из 15 возможных значений. Ваше приложение должно быть способно обработать любую из этих ошибок.
| Код | Описание |
|---|---|
| accessDenied | У вызывающей стороны нет разрешения на выполнение действия. |
| activityLimitReached | Действия приложения или пользователя превысили ограничения. |
| generalException | Произошла неуказанная ошибка. |
| invalidRange | Указан недопустимый или недоступный диапазон байтов. |
| invalidRequest | Запрос имеет неправильный формат или содержит ошибку. |
| itemNotFound | Не удалось найти ресурс. |
| malwareDetected | В запрошенном ресурсе обнаружена вредоносная программа. |
| nameAlreadyExists | Элемент с указанным именем уже существует. |
| notAllowed | Действие запрещено системой. |
| notSupported | Запрос не поддерживается в системе. |
| resourceModified | Обновляемый ресурс изменился с момента последнего чтения вызывающей стороной. Как правило, не совпадают теги eTag. |
| resyncRequired | Разностный токен больше не действителен, а приложение должно сбросить состояние синхронизации. |
| serviceNotAvailable | Служба недоступна. Повторите запрос через некоторое время. Возможно, существует заголовок Retry-After. |
| quotaLimitReached | Пользователь превысил квоту. |
| unauthenticated | Вызывающий объект не прошел аутентификацию. |
Объект innererror может рекурсивно содержать большее количество объектов innererror с дополнительными более конкретными кодами ошибок. Обрабатывая ошибку, приложения должны перебирать все доступные коды ошибок и использовать самую подробную и понятную. В конце этой страницы приведено несколько более подробных кодов.
Чтобы убедиться, что объект ошибки представляет собой ожидаемую ошибку, необходимо перебрать объекты innererror и найти ожидаемые коды ошибок. Например:
public bool IsError(string expectedErrorCode)
{
OneDriveInnerError errorCode = this.Error;
while (null != errorCode)
{
if (errorCode.Code == expectedErrorCode)
return true;
errorCode = errorCode.InnerError;
}
return false;
}
Полный пример правильной обработки ошибок см. в статье Обработка кодов ошибок в OneDrive.
Свойство message в корне содержит сообщение об ошибке, предназначенное для разработчика. Сообщения об ошибках не локализованы и не предназначены для пользователя. Приложение не должно обрабатывать значения message, так как они могут измениться в любое время и часто содержат динамические сведения, связанные с неудачным запросом. Приложение должно обрабатывать только те коды ошибок, которые возвращаются в свойствах code.
Дополнительные сведения о ресурсе, возвращаемом в ответе с ошибкой, см. в статье Тип ресурса Error.
Подробные коды ошибок
Ниже приведены некоторые дополнительные коды ошибок приложения, связанных с вложенными объектами innererror. Приложениям необязательно обрабатывать их, но при необходимости они могут делать это. Служба в любое время может добавить новые коды ошибок или прекратить возвращать какие-либо старые коды, поэтому важно, чтобы все приложения могли обрабатывать 15указанных выше базовых кодов.
| Код | Описание |
|---|---|
| accessRestricted | Доступ разрешен только владельцу элемента. |
| cannotSnapshotTree | Не удалось получить согласованный разностный моментальный снимок. Повторите попытку позже. |
| childItemCountExceeded | Достигнуто максимальное количество дочерних элементов. |
| entityTagDoesNotMatch | Тег ETag не соответствует текущему значению элемента. |
| fragmentLengthMismatch | Объявленный общий размер этого фрагмента отличается от размера сеанса отправки. |
| fragmentOutOfOrder | Фрагмент передан не по порядку. |
| fragmentOverlap | Переданный фрагмент перекрывает существующие данные. |
| invalidAcceptType | Недопустимый тип входных данных. |
| invalidParameterFormat | Недопустимый формат параметра. |
| invalidPath | Имя содержит недопустимые символы. |
| invalidQueryOption | Недопустимый параметр запроса. |
| invalidStartIndex | Недопустимый начальный индекс. |
| lockMismatch | Маркер блокировки не соответствует существующей блокировке. |
| lockNotFoundOrAlreadyExpired | В данный момент для элемента не задана действительная блокировка. |
| lockOwnerMismatch | Идентификатор владельца блокировки не соответствует указанному идентификатору. |
| malformedEntityTag | Неправильный формат заголовка тега ETag. Теги ETag должны представлять собой строки, заключенные в кавычки. |
| maxDocumentCountExceeded | Достигнуто максимальное количество документов. |
| maxFileSizeExceeded | Превышен максимальный размер файла. |
| maxFolderCountExceeded | Достигнуто максимальное количество папок. |
| maxFragmentLengthExceeded | Превышен максимальный размер файла. |
| maxItemCountExceeded | Достигнуто максимальное количество элементов. |
| maxQueryLengthExceeded | Превышена максимальная длина запроса. |
| maxStreamSizeExceeded | Превышен максимальный размер потока. |
| parameterIsTooLong | Превышена максимальная длина параметра. |
| parameterIsTooSmall | Размер параметра меньше минимального значения. |
| pathIsTooLong | Превышена максимальная длина пути. |
| pathTooDeep | Достигнуто максимальное число уровней в иерархии папок. |
| propertyNotUpdateable | Свойство не поддерживает обновление. |
| resyncApplyDifferences | Требуется повторная синхронизация. Замените все локальные элементы элементами сервера (в том числе удаленные), если вы уверены, что в службу были внесены все локальные изменения при последней синхронизации. Отправьте все локальные изменения, не загруженные на сервер. |
| resyncRequired | Требуется повторная синхронизация. |
| resyncUploadDifferences | Требуется повторная синхронизация. Отправьте все локальные элементы, не возвращенные службой, и все файлы, отличающиеся от соответствующих файлов на сервере (сохраняйте обе копии, если вы не знаете, какая из них более актуальна). |
| serviceNotAvailable | Сервер не может обработать текущий запрос. |
| serviceReadOnly | Ресурс временно доступен только для чтения. |
| throttledRequest | Слишком много запросов. |
| tooManyResultsRequested | Запрошено слишком много результатов. |
| tooManyTermsInQuery | Запрос содержит слишком много условий. |
| totalAffectedItemCountExceeded | Операция запрещена, так как количество задействованных элементов превышает пороговое значение. |
| truncationNotAllowed | Усечение данных запрещено. |
| uploadSessionFailed | Ошибка сеанса отправки. |
| uploadSessionIncomplete | Сеанс отправки не завершен. |
| uploadSessionNotFound | Сеанс отправки не найден. |
| virusSuspicious | Этот документ подозрительный и может содержать вирус. |
| zeroOrFewerResultsRequested | Запрошено ноль или меньше результатов. |