Сообщения об ошибках и типы ресурсов 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)	Запрос не может быть обработан из-за конфликта с текущим состоянием. Например, может отсутствовать указанная родительская папка. Для Directory_ConcurrencyViolation исключения можно повторить запрос после некоторой задержки. Можно использовать механизм экспоненциальной повторной попытки отката. Если заголовок Retry-After присутствует, это значение можно использовать для задержки между повторными попытками.
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, что и объект ошибки верхнего уровня. Если запрос состоит из нескольких операций, таких как массовая или пакетная операция, необходимо возвращать независимую ошибку для каждой операции. В этом случае список сведений заполняется этими отдельными ошибками.