分享方式：

要求服務 API 錯誤碼

  • 文章

Microsoft Entra 已驗證的識別碼包括要求服務 REST API，而此 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 date 錯誤的時間。
mscv 字串 內部 Microsoft 代碼。
error 錯誤 外部錯誤物件

錯誤類型

error 物件現在符合從 API 呼叫所傳回的 HTTP 狀態碼，以讓開發人員更輕鬆地處理錯誤。

屬性 類型​ 描述
code 字串 符合 HTTP 狀態碼的傳回錯誤碼。
message 字串 也相依於所傳回 HTTP 狀態碼的標準化錯誤訊息。
innererror Innererror 提供錯誤原因的詳細資料。

錯誤碼和訊息

以下是對應至所傳回不同 HTTP 狀態碼的可能最上層 code 值。

HTTP 狀態碼 code 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 要求太多，請稍後再試一次。
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 欄位包含找不到的資源名稱/識別碼。
tokenError 針對權杖 (例如 JWT) 和類似項目的任何驗證問題所傳回。 target 欄位包含導致問題的權杖名稱 (適用時)。
transientError 如果用戶端在稍後的階段重試要求，則會在用戶端可能可以取得成功回應的所有情況下傳回。 此代碼的傳回時機常見範例是傳回 HTTP 429 代碼時

下一步