Сообщения об ошибках и типы ресурсов Microsoft Graph
Ошибки в Microsoft Graph возвращаются с помощью стандартных кодов состояния HTTP и объекта ответа на ошибку JSON.
Коды состояния HTTP
В приведенной ниже таблице представлен список возможных кодов состояния HTTP и их описаний.
Код состояния | Сообщение о состоянии | Описание |
---|---|---|
400 | Неправильный запрос (Bad Request) | Не удается обработать запрос, так как он имеет неправильный или неправильный формат. |
401 | Не авторизован (Unauthorized) | Требуемые сведения о проверке подлинности отсутствуют или недопустимы для ресурса. |
402 | Требуется оплата | Требования к оплате для API не выполнены. |
403 | Запрещено | Доступ к запрошенному ресурсу запрещен. Пользователь может не иметь достаточно разрешений или не иметь требуемую лицензию. Важный: Если к ресурсу применяются политики условного доступа, HTTP 403; Forbidden error=insufficient_claims может быть возвращено сообщение. Дополнительные сведения о Microsoft Graph и условном доступе см. в статье Руководство разработчика по Microsoft Entra условного доступа. |
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) | Не удается обработать запрос, так как он семантически неверен. |
423 | Заблокирован | Ресурс заблокирован. |
429 | Слишком много запросов (Too Many Requests) | Клиентское приложение было отрегулировано и не должно пытаться повторить запрос, пока не прошло некоторое время. |
500 | Внутренняя ошибка сервера (Internal Server Error) | При обработке запроса возникла внутренняя ошибка сервера. |
501 | Не реализовано (Not Implemented) | Запрашиваемая функция не реализована. |
503 | Служба недоступна | Служба недоступна из-за перегрузки или отключена для проведения технических работ. Вы можете повторить запрос через некоторое время, которое может быть указано в заголовке Retry-After. |
504 | Истекло время ожидания шлюза (Gateway Timeout) | Сервер, выступая в качестве прокси-сервера, не получил своевременный ответ от вышестоящий сервера, к нему нужно было получить доступ при попытке завершить запрос. |
507 | Недостаточно места (Insufficient Storage) | Достигнута максимальная квота хранилища. |
509 | Превышено ограничение пропускной способности | Пропускная способность приложения отрегулирована из-за превышения максимально допустимой пропускной способности. Приложение сможет повторить запрос по истечении некоторого времени. |
Сообщение об ошибке — это один объект JSON, содержащий одно свойство error. Этот объект включает все сведения об ошибке. Вы можете использовать возвращенные сведения вместо кода состояния HTTP или вместе с ним. Ниже представлен пример полного текста ошибки JSON.
{
"error": {
"code": "badRequest",
"message": "Uploaded fragment overlaps with existing data.",
"innerError": {
"code": "invalidRange",
"request-id": "request-id",
"date": "date-time"
}
}
}
Тип ресурса ошибки
Ресурс ошибки возвращается, если при обработке запроса происходит ошибка.
Ответы об ошибках соответствуют определению, описанного в руководстве по REST API Майкрософт.
Представление JSON
Ресурс ошибки состоит из одного ресурса:
{
"error": {
"code": "string",
"message": "string",
"innererror": {
"code": "string"
},
"details": []
}
}
Имя свойства | Значение | Описание |
---|---|---|
code | string | Строка с кодом возникшей ошибки |
message | string | Готовое сообщение разработчика об ошибке, которая произошла. Это не должно отображаться для пользователя напрямую. |
innererror | Объект error | Необязательный параметр. Дополнительный объект ошибки, который может быть более конкретным, чем ошибка верхнего уровня. |
details | error object | Необязательный параметр. Список дополнительных объектов ошибок, которые могут обеспечить разбивку нескольких ошибок, возникших при обработке запроса. |
Свойства
Свойство code содержит машиночитаемое значение, которое можно использовать для зависимости в коде.
Объект innererror может рекурсивно содержать больше объектов innererror с дополнительными, более конкретными свойствами кодов ошибок. При обработке ошибки приложения должны циклически просматривать все доступные коды вложенных ошибок и использовать наиболее подробный код, который они понимают.
Свойство message — это понятное для человека значение, описывающее условие ошибки. Не зависимостей от содержимого этого значения в коде.
Свойство message в корневом каталоге содержит сообщение об ошибке, предназначенное для чтения разработчиком. Сообщения об ошибках не локализованы и не должны отображаться непосредственно пользователю. При обработке ошибок код не должен зависеть от значений свойств сообщения , так как они могут измениться в любое время и часто содержат динамическую информацию, относясь к сбою запроса. Код следует использовать только для кодов ошибок, возвращаемых в свойствах кода .
Свойство details — это необязательный массив объектов ошибок, имеющих тот же формат JSON, что и объект ошибки верхнего уровня. В случае запроса, состоящего из нескольких операций, таких как массовая или пакетная операция, может потребоваться возврат независимой ошибки для каждой операции. В этом случае список сведений заполняется этими отдельными ошибками.