请求服务 API 错误代码

项目
10/29/2023

注意

Microsoft Entra 验证 ID 现在是 Microsoft Entra 验证 ID 和 Microsoft Entra 产品系列的一部分。详细了解标识解决方案 Microsoft Entra 系列，并开始使用统一 Microsoft Entra 管理中心。

Microsoft Entra Verified ID 包括请求服务 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."
  }
}

该格式现在更改为以下格式，以实现更简单的错误处理和更好的故障排除支持。在新的格式中，外部错误代码和消息字段具有标准化值，而 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`	字符串	自动生成的请求 ID。
`date`	date	出错时间。
`mscv`	string	内部 Microsoft 代码。
`error`	错误	外部错误对象

错误类型

error 对象现在与从 API 调用返回的 HTTP 状态代码匹配，以便开发人员更容易地处理错误。

属性	类型	说明
`code`	字符串	与 HTTP 状态代码匹配的返回错误代码。
`message`	字符串	也依赖于返回的 HTTP 状态代码的标准化错误消息。
`innererror`	Innererror	提供错误原因的详细信息。

错误代码和消息

下面是映射到返回的不同 HTTP 状态代码的可能的顶级 code 值。

HTTP 状态代码	code	message
400	badRequest	请求无效。
401	未经授权的	请求的资源需要身份验证
403	已禁止	缺少实现此请求的权限。
404	notFound	请求的资源不存在。
405	methodNotAllowed	请求的资源上不允许请求的方法。
406	notAcceptable	不支持请求的响应格式。
408	requestTimeout	请求超时。
409	冲突	由于服务器冲突，服务器无法完成请求。
410	不存在	请求的资源不再可用。
411	contentLengthRequired	缺少内容长度标头。
412	preconditionFailed	此请求的先决条件失败。
413	payloadTooLarge	有效负载太大。
414	uriTooLong	URI 太长。
415	unsupportedMediaType	不支持指定的媒体类型。
416	rangeNotSatisfiable	无法满足请求的数据范围。
417	expectationFailed	无法满足 Expect 标头。
421	misdirectedRequest	无法为此请求生成响应。
422	unprocessableEntity	请求包含语义错误。
423	locked	源或目标资源已锁定。
429	tooManyRequests	请求太多，请稍后再试。
431	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"
    }
  }
}

属性	类型	说明
`code`	字符串	内部错误代码。包含基于错误类型的标准化代码
`message`	字符串	内部错误消息。包含错误的详细消息。在此示例中，`includeQRCode` 字段的类型不正确。
`target`	字符串	可选。目标包含请求中导致此错误的字段。此字段是可选的，可能不存在，具体取决于错误类型。

内部错误代码

代码	说明
`badOrMissingField`	当请求发生验证问题时返回。 `target` 字段包含请求中导致该问题的字段。
`notFound`	找不到客户端请求的资源时返回。 `target` 字段包含找不到的资源名称/ID。
`tokenError`	针对 JWT 等令牌上出现的任何验证问题返回。如果适用，`target` 字段包含导致问题的令牌名称。
`transientError`	如果客户端在后续阶段重试请求，则针对客户端可能会获得成功的响应的所有情况返回。返回此代码时的常见示例是返回 HTTP 429 代码

通过