请求服务 API 错误代码

  • 项目

注意

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 代码

后续步骤