Коды ошибок API службы запросов

Статья
01/31/2025

Проверенный идентификатор Microsoft Entra включает REST API службы запросов, который позволяет выдавать и проверять учетные данные. В этой статье указаны коды ошибок для API службы запросов.

Объект error

Во время общедоступной предварительной версии API службы запросов вернул ошибки в следующем формате.

{
  "requestId": "4bb6726f77af7623ab52962323016442",
  "date": "Thu, 28 Apr 2022 14:30:54 GMT",
  "mscv": "17ppwf3uxR10MfRR.1",
  "error": {
    "code": "client_request.invalid_include_qr_code",
    "message": "The request contains `includeQRCode`, but it is not boolean."
  }
}

Теперь этот формат изменяется на следующий формат, чтобы упростить обработку ошибок и улучшить поддержку устранения неполадок. В новом формате внешние ошибки коде и полях сообщений имеют стандартизированные значения, а объект innererror предоставляет сведения о том, что вызвало ошибку.

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}

Свойство	Тип	Описание
`requestId`	струна	Идентификатор автогенерированного запроса.
`date`	дата	Время ошибки.
`mscv`	струна	Внутренний код Майкрософт.
`error`	ошибка	Внешний объект ошибки

Тип ошибки

Объект error теперь соответствует коду состояния HTTP, возвращенным из вызова API, чтобы упростить обработку ошибок для разработчиков.

Свойство	Тип	Описание
`code`	струна	Код ошибки возврата, соответствующий коду состояния HTTP.
`message`	струна	Стандартизированное сообщение об ошибке, которое также зависит от возвращаемого кода состояния HTTP.
`innererror`	Innererror	Укажите сведения о том, что вызвало ошибку.

Коды ошибок и сообщения

Ниже приведены возможные значения верхнего уровня code, которые сопоставляются с различными возвращаемыми кодами состояния HTTP.

Код состояния HTTP	код	Сообщение
400	badRequest	Запрос недопустим.
401	несанкционированный	Запрошенный ресурс требует проверки подлинности
403	запретный	Отсутствующие разрешения для выполнения этого запроса.
404	notFound	Запрошенный ресурс не существует.
405	methodNotAllowed	Запрошенный метод не разрешен для запрошенного ресурса.
406	notAcceptable	Запрошенный формат ответа не поддерживается.
408	requestTimeout	Время ожидания запроса.
409	конфликт	Сервер не может выполнить запрос из-за конфликта сервера.
410	потерянный	Запрошенный ресурс больше недоступен.
411	contentLengthRequired	Отсутствует заголовок Content-Length.
412	предусловие	Не удалось выполнить предварительный условий для этого запроса.
413	полезные данныеTooLarge	Полезные данные слишком большие.
414	uriTooLong	URI слишком длинный.
415	unsupportedMediaType	Указанный тип носителя не поддерживается.
416	rangeNotSatisfiable	Запрошенный диапазон запрошенных данных не может быть удовлетворен.
417	ожиданиеFailed	Ожидаемый заголовок не может быть удовлетворен.
421	неправильное направлениеRequest	Не удалось создать ответ для этого запроса.
422	unprocessableEntity	Запрос содержит семантические ошибки.
423	запертый	Исходный или целевой ресурс заблокирован.
429	tooManyRequests	Слишком много запросов, повторите попытку позже.
431	requestHeaderFieldsTooLarge	Поле заголовка запроса слишком велико.
500	internalServerError	На сервере произошла универсальная ошибка.
501	notImplemented	Сервер не поддерживает запрошенную функцию.
502	badGateway	неправильный ответ, полученный от другого шлюза.
503	serviceUnavailable	Сервер временно недоступен, повторите попытку позже.
504	gatewayTimeout	Время ожидания, полученное от другого шлюза.
507	недостаточного объема данных	Не удалось сохранить данные для запроса.

Тип внутренней ошибки

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

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}

Свойство	Тип	Описание
`code`	струна	Код внутренней ошибки. Содержит стандартизованный код на основе типа ошибки
`message`	струна	Внутреннее сообщение об ошибке. Содержит подробное сообщение об ошибке. В этом примере поле `includeQRCode` имеет неправильный тип.
`target`	струна	Необязательный. Целевой объект содержит поле в запросе, вызывающего эту ошибку. Это поле является необязательным и может не присутствовать в зависимости от типа ошибки.

Внутренние коды ошибок

Код	Описание
`badOrMissingField`	возвращается при возникновении проблем с проверкой запроса. Поле `target` содержит поле в запросе, вызывающее проблему.
`notFound`	возвращается при запросе ресурса, запрашиваемого клиентом. Поле `target` содержит имя ресурса или идентификатор, который не найден.
`tokenError`	Возвращается для любых проблем с проверкой для токенов, таких как веб-токен JSON (JWT) и подобные. Поле `target` содержит имя маркера, вызывающее проблему, если применимо.
`transientError`	Возвращается для всех случаев, когда клиент может получить успешный ответ, если он повторите запрос на более позднем этапе. Распространенный пример возврата этого кода — при возврате кода HTTP 429

Дальнейшие действия

спецификация API выдачи
спецификации API презентации

Поделиться через