共用方式為

要求服務 API 錯誤碼

  • 發行項

Microsoft Entra 已驗證的標識碼包含要求服務 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 字串 自動產生的要求標識碼。
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] 欄位包含找不到的資源名稱/標識符。
tokenError 針對 JSON Web 令牌 （JWT） 等權杖上的任何驗證問題傳回 。 當適用時，[target] 字段包含造成問題的令牌名稱。
transientError 如果用戶端在稍後階段重試要求，則傳回給用戶端可能會取得成功回應的所有案例。 傳回此程式代碼的常見範例是傳回 HTTP 429 程式代碼時

後續步驟