錯誤碼和錯誤處理 | Graph API 概念

  • 發行項

**適用於︰**Graph API | Azure Active Directory

使用 Azure Active Directory Graph API 的用戶端應用程式應實作錯誤處理邏輯，以盡可能適當地回應各種不同的情況，並盡可能提供最佳體驗給客戶。 本主題討論 Azure AD Graph API 傳回的錯誤類型，並提供有關如何處理錯誤的一般指引。

重要

我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源，而不是使用 Azure AD Graph API。我們目前致力於開發 Microsoft Graph，對於 Azure AD Graph API 則沒有進一步增強的計劃。Azure AD Graph API 仍適用於非常少數的案例；如需詳細資訊，請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD Graph (英文) 部落格文章。

處理 Graph API 錯誤

錯誤類型

Graph API 錯誤發生的類別如下。

  • 用戶端錯誤。 用戶端錯誤以 400 系列 HTTP 狀態碼表示。 包括具有無效值的物件、遺漏必要屬性或屬性值的物件、嘗試存取不存在的資源、嘗試更新唯讀屬性，以及省略必要的授權權杖。 若要解決這些錯誤，請修正基本問題，再重試要求。
  • 伺服器錯誤。 伺服器錯誤以 500 系列的 HTTP 狀態碼表示，例如暫時性目錄失敗。 大部分的錯誤是暫時性錯誤，可透過重試要求來解決。
  • 網路/通訊協定錯誤。 傳送要求或接收回應時，可能會發生各種網路相關錯誤，例如主機名稱解析錯誤、提早關閉連線及 SSL 交涉錯誤。 大部分的此類錯誤無法透過重試解決，您必須修正基本問題。 不過，重試要求有可能解決某些問題，例如主機名稱解析失敗或逾時。

錯誤訊息結構

Graph API 錯誤的主體已格式化，包含 HTTP 狀態碼、訊息和值。 請在您的錯誤處理邏輯中使用這些錯誤主體的屬性。

注意：由於要求是透過 Proxy 和閘道服務進行路由傳送，因此某些 HTTP 回應可能不會包含代碼/訊息/值的回應主體。 請務必包含僅根據 HTTP 狀態碼來處理錯誤的預設邏輯。

以下是 HTTP 400 Request_BadRequest 錯誤的範例。

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

每個訊息主體包含代碼、訊息和值屬性。

  • 代碼：設計您的錯誤處理邏輯並依代碼分支。

    "code" : "Request_BadRequest"

  • 訊息：表示人們可讀取之錯誤訊息的語言/值 Tuple。 其內容位於值欄位中。 在下列範例中，由於遺漏 mailNickname 屬性的值，因此要求失敗。

    "message" : {
     "lang" : "en",
     "value" : "A value is required for property 'mailNickname' of resource 'Group'."
}

  • 值：名稱/值組的集合，提供有關失敗本質的詳細資訊。 下列範例中未包括值。

    "values" : null

錯誤碼參考

HTTP 錯誤碼

下列資料表列出 Graph API 錯誤碼、錯誤訊息和更正錯誤時應考量的動作。

一般而言，回應 HTTP 500 系列的錯誤時，最好搭配常態分佈因素以逐漸增長的時間間隔分配重試 (「重試輪詢間隔時間延長」)。 400 系列的錯誤則表示務必先修正問題後再重試。

HTTP 狀態碼 錯誤碼 錯誤訊息 詳細資料
400 Directory_ExpiredPageToken 指定頁面的權杖值已過期，並已無法繼續包含在您的要求中。  
400 Directory_ResultSizeLimitExceeded 已超過結果大小限制 由於相關聯的結果太多以致無法完成要求。此錯誤發生的頻率極低。
400 DomainVerificationCodeNotFound   因為驗證處理序找不到任何具有相符驗證碼的 TXT 記錄，導致網域驗證失敗。
400 ObjectConflict 此公司未經驗證的網域中已有此網域名稱。  
400 ObjectConflict 此公司經過驗證的網域中已有此網域名稱。  
400 ObjectInUse 無法刪除目前正由使用者、群組或多租用戶應用程式參考的網域  
400 ObjectPendingDeletion   無法驗證現有待刪除的網域。
400 ObjectPendingTakeover 租用戶接管期間無法刪除網域  
400 Request_BadRequest 不正確的要求。請修正要求後，再試一次。 表示要求中有錯誤，例如無效的屬性值或不支援的查詢引數。請修正要求後再試一次。
400 Request_DataContractVersionMissing 遺漏了資料合約版本參數。將 api-version 做為查詢參數包含在您所有的要求中。  
400 Request_InvalidDataContractVersion 指定的 api-version 無效。值必須完全符合支援的版本。  
400 Request_InvalidRequestUrl 要求 URL 無效。要求應該要像 /tenantdomainname/Entity 或 /$metadata。租用戶網域名稱可以是任何已驗證或未驗證的網域名稱或內容識別碼。  
400 Request_UnsupportedQuery   不支援 GET 要求。修正要求參數，然後再試一次。
401 Authentication_ExpiredToken 您的存取 Token 已過期。請予以更新後再提交要求。 存取 Token 已過期。請更新 Token 然後再重新提交。
401 Authentication_MissingOrMalformed 存取 Token 遺漏或格式錯誤。 授權標頭中遺漏 access_token 值或其值格式錯誤。這是必要值。驗證 Token 中應使用此值。
401 Authorization_IdentityDisabled 呼叫的應用程式主體已停用。 存取 Token 所指定的主體位於目錄中，但是已經停用。請重新啟用目錄中的帳戶，然後再試一次。
401 Authorization_IdentityNotFound 無法為呼叫的應用程式建立身分識別。 在目錄中找不到存取 Token 所指定的主體。發生此錯誤可能是因為 Token 已過時、已從目錄刪除主體，或是目錄同步作業延遲。
403 Authentication_Unauthorized 未授權的要求。 Token 包含無效或不支援的宣告。請再次取得要求 Token，然後重試要求。
403 Authorization_RequestDenied 指定的認證沒有足夠的權限提出這項要求。 由於權限不足，要求遭到拒絕。例如，非管理主體沒有刪除資源的權限。
403 Directory_QuotaExceeded 超出了 {tenantName} 的目錄物件配額限制。請要求您的系統管理員提高配額上限，或是刪除物件以降低已使用的配額。 已經超過目錄配額。租用戶可能擁有太多物件，或者物件可能有太多的值。這也會在主體上建立太多的物件時發生。請為租用戶或主體提高允許的物件計數上限，或是減少建立/更新要求中所包含的值數目。
404 Directory_ObjectNotFound 無法從目錄讀取公司資訊。  
404 Request_ResourceNotFound 資源 {resource} 不存在，或其任一個查詢的參考屬性物件不存在。 由 URI 所識別的資源不存在。請修訂其值後再重試要求。
409 Request_MultipleObjectsWithSameKeyValue 預期的結果為單一資源，但是找到多個資源。請更新物件以解決衝突。 此錯誤可能會在有兩個或以上的物件擁有相同的金鑰值時發生，例如當兩位使用者擁有相同的 UserPrincipalName 時。
429   過多要求。 此錯誤會在要求受到節流時發生。建議的等候時間會在回應標頭的 Retry-After 值中傳回。請在經過建議的秒數之後重試要求。
500 Service_InternalServerError 發生內部伺服器錯誤。 處理要求時發生內部伺服器錯誤。
502 [全部] “...服務無法使用...” 作為閘道或 Proxy 的伺服器在另一部伺服器處理要求時發生錯誤。請等候幾分鐘後再重試要求。
503 Directory_ConcurrencyViolation 因對租用戶做出同時要求而產生的錯誤。請稍待片刻，然後再試一次。  
503   DNS 驗證期間發生錯誤 (請注意︰導致此問題的原因有許多種，例如 DNS 目前停機)。  
  Authentication_Unknown 內部伺服器錯誤。 當其他錯誤碼不適用時，會使用此錯誤碼。
  Authentication_UnsupportedTokenType 顯示的 Token 類型不會進行處理。僅支援持有者 Token。 Token 類型不受支援。請修正 Token 類型後再重試一次要求。
  Directory_BindingRedirection 無法在本機取得租用戶資訊。請使用下列 URL 以取得資訊。 當無法從資料中心取得租用戶分割區時，用戶端必須連接到回應所傳回的 URL。
  Directory_BindingRedirectionInternalServerError 無法在本機取得租用戶資訊。伺服器嘗試填入最靠近的資料中心端點時發生內部錯誤。 若一旦發生繫結重新導向例外狀況，便會填入最靠近服務的資料中心端點的清單。此錯誤表示在填入該份清單時發生例外狀況。請重試查詢。
  Directory_CompanyNotFound 無法從目錄讀取公司資訊。 從目錄服務載入公司資訊時發生錯誤。
  Directory_ReplicaUnavailable 無法使用慣用的複本。請在不加任何複本工作階段金鑰標頭情況下重試。 請刪去 x-ms-replica-session-key 標頭然後重試。
  Headers_DataContractVersionMissing 遺漏了資料合約版本標頭。要求中請包含 x-ms-dirapi-data-contract-version。 要求中遺漏了用戶端合約版本。
  Headers_HeaderNotSupported 目前不支援標頭 {0}。 要求包含了不支援的 HTTP 標頭。請變更標頭後再重試一次要求。
  Request_InvalidReplicaSessionKey 提供的複本工作階段金鑰無效。 請修正複本工作階段金鑰後再重試一次要求。
  Request_ThrottledPermanently 您的要求已永久節流。請連絡支援人員以解決問題。 租用戶持續重複超過 Token 要求率限制。來自租用戶的要求會遭到拒絕，直到服務重新交涉。如需協助，請連絡 Microsoft 支援服務。

其他資源