要求服務 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 string 自動產生的要求識別碼。
date date 錯誤的時間。
mscv string 內部 Microsoft 程式碼。
error 錯誤 外部錯誤物件

錯誤類型

物件 error 現在會比對 API 呼叫傳回的 HTTP 狀態碼，讓開發人員更容易處理錯誤。

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

錯誤碼和訊息

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

HTTP 狀態碼 code message
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 無法滿足 Expect 標頭。
421 misdirectedRequest 無法產生此要求的回應。
422 unprocessableEntity 要求包含語意錯誤。
423 鎖 來源或目的地資源已鎖定。
429 tooManyRequests 太多要求，請稍後再試一次。
431 requestHeaderFieldsTooLarge 要求標頭欄位太大。
500 internalServerError 伺服器上發生一般錯誤。
501 notImplemented 伺服器不支援要求的函式。
502 badGateway 從另一個閘道收到不正確的回應。
503 serviceUnavailable 伺服器暫時無法使用，請稍後再試一次。
504 gatewayTimeout 從另一個閘道接收的逾時。
507 不足儲存體 無法儲存要求的資料。

內部錯誤類型

內部錯誤物件包含適用于開發人員的錯誤特定詳細資料，可協助調查目前的失敗。

{
  "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 string 內部錯誤碼。 根據錯誤的類型，包含標準化的程式碼
message string 內部錯誤訊息。 包含錯誤的詳細訊息。 在此範例中 includeQRCode ，欄位的類型錯誤。
target string 選擇性。 目標包含要求中造成此錯誤的 欄位。 此欄位是選擇性欄位，可能不存在，視錯誤類型而定。

內部錯誤碼

代碼 描述
badOrMissingField 在要求發生驗證問題時傳回。 欄位 target 包含要求中造成問題的欄位。
notFound 找不到用戶端要求的資源時傳回 。 欄位 target 包含找不到的資源名稱/識別碼。
tokenError 針對 JWT 等權杖上的任何驗證問題傳回 。 如果適用，欄位 target 包含造成問題的權杖名稱。
transientError 如果用戶端在稍後階段重試要求，則傳回給用戶端可能會取得成功回應的所有案例。 傳回此程式碼的常見範例是傳回 HTTP 429 程式碼時

下一步