Сообщения об ошибках и типы ресурсов 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, что и объект ошибки верхнего уровня. В случае запроса, состоящего из нескольких операций, таких как массовая или пакетная операция, может потребоваться возврат независимой ошибки для каждой операции. В этом случае список сведений заполняется этими отдельными ошибками.