Microsoft Graph 错误响应和资源类型

使用标准的 HTTP 状态代码以及 JSON 错误响应对象返回 Microsoft Graph 中的错误。

HTTP 状态代码

下表列出并描述可以返回的 HTTP 状态代码。

状态代码	状态消息	说明
400	错误的请求 (Bad Request)	无法处理请求，因为格式有误或者不正确。
401	未经授权 (Unauthorized)	资源所需的身份验证信息缺少或无效。
403	禁止访问 (Forbidden)	对于请求的资源，访问被拒绝。用户可能没有足够的权限。 重要说明： 如果向资源应用了条件访问策略，可能会返回 HTTP 403 禁止错误 (error=insufficent_claims)。 有关 Microsoft Graph 和条件访问的详细信息，请参阅 Azure Active Directory 条件性访问开发人员指南
404	未找到 (Not Found)	所请求的资源不存在。
405	方法不允许 (Method Not Allowed)	请求中的 HTTP 方法在资源上不允许。
406	不接受 (Not Acceptable)	该服务不支持“Accept”标头中请求的格式。
409	冲突 (Conflict)	当前状态与请求预期的状态的冲突。例如，指定的父文件夹可能不存在。
410	不存在 (Gone)	所请求的资源在服务器不再可用。
411	需要长度 (Length Required)	请求上需要 Content-Length 标头。
412	前提条件不满足 (Precondition Failed)	请求中提供的前提条件（例如“If-Match”标头）与资源的当前状态不匹配。
413	请求实体太大 (Request Entity Too Large)	请求的大小超出最大限制。
415	媒体类型不受支持 (Unsupported Media Type)	请求的内容类型的格式不受服务支持。
416	请求的范围不满足 (Requested Range Not Satisfiable)	指定的字节范围无效或不可用。
422	实体无法处理 (Unprocessable Entity)	无法处理请求，因为语义上不正确。
423	已锁定	正在访问的资源被锁定。
429	请求过多 (Too Many Requests)	客户端应用程序已被限制，经过一段时间之后再尝试重复的请求。
500	内部服务器错误 (Internal Server Error)	处理请求时出现内部服务器错误。
501	未实现 (Not Implemented)	所请求的功能未实现。
503	服务不可用	服务暂时无法维护或过载。你可以在延迟后重复该请求，其长度可以在 Retry-After 标头中指定。
504	网关超时	服务器在充当代理时，没有收到它在尝试完成请求时需要访问的来自上游服务器的及时响应。可能会与 503 错误同时出现。
507	存储不足 (Insufficient Storage)	已达到最大存储配额。
509	超出带宽限制 (Bandwidth Limit Exceeded)	您的应用因超出最大带宽上限而被限制。应用可以在等待一段时间之后再重试该请求。

错误响应是单个 JSON 对象，包含名为“error”的单个属性。此对象包括错误的所有详细信息。除了 HTTP 状态代码外，还可以使用此处返回的信息，或者使用此信息替代 HTTP 状态代码。以下是完整的 JSON 错误正文示例。

{
  "error": {
    "code": "invalidRange",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "requestId": "request-id",
      "date": "date-time"
    }
  }
}

错误的资源类型

只要处理请求的过程中出现错误，就会返回错误资源。

错误响应遵循错误响应 OData v4 规范中的定义。

JSON 表示形式

错误资源包括以下资源：

{
  "error": { "@odata.type": "odata.error" }  
}

odata.error 资源类型

错误响应内是错误资源，其中包括以下属性：

{
  "code": "string",
  "message": "string",
  "innererror": { "@odata.type": "odata.error" }
}

属性名称	值	说明
code	string	发生的错误的错误代码字符串
message	string	关于发生的错误的开发人员就绪消息。该内容不应直接显示给用户。
innererror	error object	可选。可能比顶级错误更具体的其他错误对象。

代码属性

code 属性包含下列可能值之一。您的应用应做好准备处理任意这些错误。

代码	说明
accessDenied	调用方没有执行该操作的权限。
activityLimitReached	应用或用户已被限制。
extensionError	邮箱位于本地，并且 Exchange Server 不支持联合的 Microsoft Graph 请求，或者应用程序策略会阻止应用程序访问邮箱。
generalException	发生未指定错误。
invalidRange	指定的字节范围无效或不可用。
invalidRequest	该请求格式有误或不正确。
itemNotFound	找不到资源。
malwareDetected	所请求的资源中检测到恶意软件。
nameAlreadyExists	指定的项目名称已存在。
notAllowed	系统不允许执行此操作。
notSupported	系统不支持该请求。
resourceModified	正在更新的资源自上次调用方读取时已进行了更改，通常是 eTag 不匹配。
resyncRequired	增量令牌将不再有效，并且应用必须重置同步状态。
serviceNotAvailable	服务不可用。过段时间后再次尝试请求。可能会有 Retry-After 标头。
syncStateNotFound	找不到同步状态生成。 增量令牌已过期，必须重新进行数据同步。
quotaLimitReached	用户已达到其配额限制。
unauthenticated	调用方未进行身份验证。

innererror 对象可能以递归方式包含更多 innererror 对象，其中具有其他更多具体的错误代码。处理错误时，应用应遍历所有可用错误代码并使用它们认为最详细的错误代码。在本页底部列出了一些更详细的代码。

若要验证某个错误对象是否是你想要的错误，你必须遍历 innererror 对象，查找你想要的错误代码。例如：

public bool IsError(string expectedErrorCode)
{
    OneDriveInnerError errorCode = this.Error;
    while (null != errorCode)
    {
        if (errorCode.Code == expectedErrorCode)
            return true;
        errorCode = errorCode.InnerError;
    }
    return false;
}

有关介绍如何正确处理错误的示例，请参阅 错误代码处理。

根处的 message 属性包含供开发人员阅读的错误消息。 错误消息未本地化，并且不应直接向用户显示。 在处理错误时，代码不应根据 message 值进行分支，因为它们随时会更改，并且它们通常包含特定于失败请求的动态信息。 只应针对 code 属性中返回的错误代码进行编码。

详细的错误代码

以下是你的应用可能会在嵌套的 innererror 对象中遇到的一些其他错误。应用不需要处理这些错误，但如果它们选择，也可以处理。服务可能会随时添加新的错误代码或者停止返回的旧代码，因此所有应用都能够处理 基本错误代码 非常重要。

代码	说明
accessRestricted	访问仅限于该项目的所有者。
cannotSnapshotTree	未能获取一致的增量快照。请稍后重试。
childItemCountExceeded	已达到最大子项目数限制。
entityTagDoesNotMatch	ETag 与当前项目的值不匹配。
fragmentLengthMismatch	为此片段声明的总大小与上载会话的大小不同。
fragmentOutOfOrder	已上载的片段无序。
fragmentOverlap	上载的片段与现有数据重叠。
invalidAcceptType	接受类型无效。
invalidParameterFormat	参数格式无效。
invalidPath	名称包含无效字符。
invalidQueryOption	查询选项无效。
invalidStartIndex	开始索引无效。
lockMismatch	锁定令牌与现有锁定不匹配。
lockNotFoundOrAlreadyExpired	该项目上目前没有未过期的锁定。
lockOwnerMismatch	锁定所有者 ID 与提供的 ID 不匹配。
malformedEntityTag	ETag 标头格式不正确。ETags 必须是带引号的字符串。
maxDocumentCountExceeded	已达到最大文档数量限制。
maxFileSizeExceeded	已超出最大文件大小。
maxFolderCountExceeded	已达到最大文件夹数量限制。
maxFragmentLengthExceeded	已超出最大文件大小。
maxItemCountExceeded	已达到最大项目数量限制。
maxQueryLengthExceeded	已超出最大查询长度。
maxStreamSizeExceeded	已达到最大流大小。
parameterIsTooLong	参数超过最大长度。
parameterIsTooSmall	参数小于最小值。
pathIsTooLong	路径超出最大长度。
pathTooDeep	已达到文件夹层次结构深度限制。
propertyNotUpdateable	属性无法更新。
provisioningNotAllowed	请求需要帐户预配，这是不允许的。
resourceBeingProvisioned	正在预配请求的资源。
resyncApplyDifferences	需要重新同步。如果您确定上次同步时服务与您的本地更改保持同步，则请将任意本地项目替换为服务器的版本（包括删除）。上载服务器并不清楚的任意本地更改。
resyncRequired	需要重新同步。
resyncUploadDifferences	需要重新同步。上载服务未返回的任意本地项目，并上载与服务器版本不同的任意文件（如果不知道哪个是最新的，就请保留两份）。
serviceNotAvailable	服务器无法处理当前的请求。
serviceReadOnly	资源暂时是只读的。
throttledRequest	请求过多。
tooManyResultsRequested	请求的结果过多。
tooManyTermsInQuery	查询中的术语过多。
totalAffectedItemCountExceeded	因为受影响的项目数量超出阈值，所以不允许该操作。
truncationNotAllowed	不允许数据截断。
uploadSessionFailed	上载会话失败。
uploadSessionIncomplete	上载会话未完成。
uploadSessionNotFound	上载会话未找到。
virusSuspicious	此文档可疑，可能存在病毒。
zeroOrFewerResultsRequested	请求的结果为零或更少。