请求服务 API 错误代码

项目
01/31/2025

Microsoft Entra 已验证 ID 包括请求服务 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`	字符串	自动生成的请求 ID。
`date`	日期	错误的时间。
`mscv`	字符串	内部Microsoft代码。
`error`	错误	外部错误对象

错误类型

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

财产	类型	描述
`code`	字符串	与 HTTP 状态代码匹配的返回错误代码。
`message`	字符串	也依赖于返回的 HTTP 状态代码的标准化错误消息。
`innererror`	Innererror	提供有关导致错误的原因的详细信息。

错误代码和消息

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

HTTP 状态代码	法典	消息
400	badRequest	请求无效。
401	未经授权	请求的资源需要身份验证
403	禁止	缺少满足此请求的权限。
404	notFound	请求的资源不存在。
405	methodNotAllowed	请求的资源上不允许使用请求的方法。
406	notAcceptable	不支持请求的响应格式。
408	requestTimeout	请求超时。
409	冲突	由于服务器冲突，服务器无法满足请求。
410	逝	请求的资源不再可用。
411	contentLengthRequired	缺少 Content-Length 标头。
412	preconditionFailed	此请求的先决条件失败。
413	payloadTooLarge	有效负载太大。
414	uriTooLong	URI 太长。
415	unsupportedMediaType	不支持指定的媒体类型。
416	rangeNotSatisfiable	无法满足所请求的数据范围。
417	expectationFailed	无法满足预期标头。
421	misdirectedRequest	无法为此请求生成响应。
422	unprocessableEntity	请求包含语义错误。
423	锁	源或目标资源已锁定。
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`	对于 JSON Web 令牌（JWT）等令牌上出现的任何验证问题，返回这些验证问题。 `target` 字段包含导致问题的令牌名称（如果适用）。
`transientError`	如果客户端在以后的阶段重试请求，则返回给客户端可能能够获取成功响应的所有情况。返回此代码的常见示例是返回 HTTP 429 代码

通过