要求服務 API 錯誤碼

發行項
07/05/2024

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 代碼時

共用方式為