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

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

  • Статья

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

Объект ошибки

В общедоступной предварительной версии 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."
  }
}

Вместо этого формата теперь используется представленный ниже, который позволяет упростить обработку ошибок и лучше поддерживает сценарии устранения неполадок. В новом формате внешний код error и поля сообщений имеют стандартизированные значения, а объект 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"
    }
  }
}
Свойство Type Описание:
requestId строка Автоматически сформированный идентификатор запроса.
date Дата Время ошибки.
mscv строка Внутренний код Майкрософт.
error Ошибка Внешний объект ошибки

Тип ошибки

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

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

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

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

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

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

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

{
  "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"
    }
  }
}
Свойство Type Описание:
code строка Код внутренней ошибки. Содержит стандартизированный код, основанный на типе ошибки.
message строка Внутреннее сообщение об ошибке. Содержит подробное сообщение об ошибке. В нашем примере поле includeQRCode имеет неправильный тип.
target строка Необязательно. Целевой объект содержит поле запроса, которое вызывает эту ошибку. Это поле является необязательным и может отсутствовать, в зависимости от типа ошибки.

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

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

Следующие шаги