要求服務 API 錯誤碼
Microsoft Entra 已驗證的識別碼包括要求服務 REST API,而此 API 可讓您核發和驗證認證。 本文指定要求服務 API 的錯誤碼。
在公開預覽期間,要求服務 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 代碼時 |