Table of contents

错误代码和错误处理 | Graph API 概念

Jimaco Brannian|上次更新日期: 2017/2/23
|
1 参与者

适用范围: 图形 API | Azure Active Directory (AD)

使用 Azure Active Directory (AD) Graph API 的客户端应用程序应实现错误处理逻辑,从而尽可能从容地应对各种不同的状况,为客户提供最佳体验。 本主题将讨论 Azure AD Graph API 返回的错误类型并就如何处理这些错误提供一般性指导。

重要事项

Azure AD Graph API 功能也可通过 Microsoft Graph 使用。Microsoft Graph 是一个统一的 API,它还包括其他 Microsoft 服务(如 Outlook、OneDrive、OneNote、Planner 和 Office Graph)的 API,这些都可以使用单个访问令牌通过单个终结点进行访问。

处理 Graph API 错误

错误类型

Graph API 错误存在于如下类别中。

  • 客户端错误。 客户端错误通过 400 系列 HTTP 状态代码表示。 它们包括对象的值无效、对象丢失需要的属性或属性值、试图访问不存在的资源、试图更新只读属性以及省略必需的授权标记。 要解决这些错误,请在重试请求前修复根本问题。
  • 服务器错误。 服务器错误由 500 系列 HTTP 状态代码表示,例如暂时性目录故障。 多数此类错误均为暂时性的,可通过重试请求得以解决。
  • 网络/协议错误。 各种网络相关错误可在发送请求或接收响应时发生,如主机名解析错误、过早关闭连接以及 SSL 协商错误。 多数此类错误不能通过重试得到解决;而必须修复根本问题。 但某些错误(主机名解析失败或超时)可通过重试请求得到解决。

错误消息结构

Graph API 错误的格式化主体包含一个 HTTP 状态代码、一条消息以及值。 在错误处理逻辑中使用错误正文的属性。

注意:某些 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"
    
  • 消息:代表人工可读错误消息的“语言/值”元组。 内容位于值字段。 在以下示例中,请求失败,因为 mailNickname 属性的值缺失。

      "message" : {
           "lang" : "en",
           "value" : "A value is required for property 'mailNickname' of resource 'Group'."
      }
    
  • :提供有关失败情况的更多信息的“名称/值”对的集合。 以下示例中不包括任何值。

      "values" : null
    

错误代码参考

HTTP 错误代码

下表列出 Graph API 错误代码、错误消息以及更正错误时要考虑的操作。

一般情况下,HTTP 500 系列错误响应重试,最好按越来越长的时间间隔分布(“按退让间隔重试”)并具有随机分布系数。 400 系列错误指示必须在重试之前修复问题。

HTTP 状态代码错误代码错误消息详细信息
400Directory_ExpiredPageToken指定的页面标记值已过期,并且不再包含到你的请求中。
400Directory_ResultSizeLimitExceeded已超过结果大小限制请求无法完成,因为它关联的结果太多。 此错误很少出现。
400DomainVerificationCodeNotFound域验证失败,因为在验证过程中找不到具有匹配的验证代码的 TXT 记录。
400ObjectConflict该域名已存在于该公司未验证的域中。
400ObjectConflict该域名已存在于该公司已验证的域中。
400ObjectInUse无法删除当前由用户、组或多租户应用程序引用的域
400ObjectPendingDeletion无法验证等待删除的现有域。
400ObjectPendingTakeover在租户接管过程中无法删除域
400Request_BadRequest错误请求。 请在重试之前修复请求。指示请求中存在错误,如无效的属性值或不支持的查询参数。 请在重试之前修复请求。
400Request_DataContractVersionMissing数据约定版本参数缺失。 在你的所有请求中加入作为查询参数的 API 版本。
400Request_InvalidDataContractVersion指定的 API 版本无效。 值必须与受支持的版本完全匹配。
400Request_InvalidRequestUrl请求 URL 无效。 请求应类似于 /tenantdomainname/Entity 或 /$metadata。 租户域名可以是任何经验证的的域名、未经验证的域名或上下文 ID。
400Request_UnsupportedQuery不支持 GET 请求。 修复请求参数,然后重试。
401Authentication_ExpiredToken你的访问令牌已过期。 请在提交请求之前续订请求。访问令牌已过期。 请续订令牌,然后重新提交。
401Authentication_MissingOrMalformed访问令牌缺失或格式不正确。授权标头中的 access_token 值缺失或格式不正确。 此值是必需的。 请在身份验证令牌中使用该值。
401Authorization_IdentityDisabled调用应用程序主体已禁用。访问令牌中指定的主体处于目录中,但是已禁用。 在目录中重新启用该帐户,然后重试。
401Authorization_IdentityNotFound无法建立调用应用程序的标识。未在目录中找到访问令牌中指定的主体。 出现这种情况的原因可能是令牌已过时、主体已从目录中删除或目录同步延迟。
403Authentication_Unauthorized未授权的请求。令牌包含无效或不支持的声明。 再次获取请求令牌,然后重试请求。
403Authorization_RequestDenied指定凭据的权限不足,无法进行此请求。请求由于权限不足而遭到拒绝。 例如,非管理主体无权删除资源。
403Directory_QuotaExceeded已超过 {tenantName} 的目录对象配额限制。 请要求管理员增加配额限制或删除对象以减少已使用的配额。已超过目录配额。 租户拥有的对象可能太多,或对象拥有的值可能太多。 当为主体创建的对象太多时,也会出现这种情况。 请增加租户或主体的最大允许对象计数,或减少创建/更新请求中包含的值的数量。
404Directory_ObjectNotFound无法从目录读取公司信息。
404Request_ResourceNotFound资源 {resource} 不存在,或是其查询引用-属性对象之一不存在。通过 URI 标识的资源不存在。 请修改该值,然后重试请求。
409Request_MultipleObjectsWithSameKeyValue结果应为单个资源,但找到了多个资源。 请更新对象来解决冲突。有两个或多个具有相同键值的对象(例如,当两个用户具有相同的 UserPrincipalName)时,会出现此错误。
429请求过多。请求处于被限制状态时会发生该错误。 响应标头的“稍后重试”值中会返回建议的等待时间。 等待建议的秒数后重试请求。
500Service_InternalServerError遇到内部服务器错误。处理请求时出现内部服务器错误。
502[全部]“...服务不可用...”用作网关或代理的服务器在处理请求时遇到来自另一个服务器的错误。 等待几分钟,然后重试请求。
503Directory_ConcurrencyViolation由于对租户发起并发请求而导致出错。 请稍等片刻,然后重试。
503DNS 验证期间出错(请注意:这可能是由各种原因引起的,例如 DNS 当前已关闭)。
Authentication_Unknown内部服务器错误。此错误代码在其他错误代码不适用时使用。
Authentication_UnsupportedTokenType提供的令牌类型未处理。 仅支持持有人令牌。不支持该令牌类型。 请在重试请求之前修改令牌类型。
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你的请求永久受到限制。 请致电支持人员以解决该问题。租户反复并持久地超过令牌请求速率限制。 来自租户的请求遭到拒绝,直至服务重新进行协商。 若要获得帮助,请与 Microsoft 支持部门联系。

其他资源

© 2017 Microsoft