Microsoft Graph 错误响应和资源类型Microsoft Graph error responses and resource types

使用标准的 HTTP 状态代码以及 JSON 错误响应对象返回 Microsoft Graph 中的错误。Errors in Microsoft Graph are returned using standard HTTP status codes, as well as a JSON error response object.

HTTP 状态代码HTTP status codes

下表列出并描述可以返回的 HTTP 状态代码。The following table lists and describes the HTTP status codes that can be returned.

状态代码Status code 状态消息Status message 说明Description
4004.0.0 错误的请求 (Bad Request)Bad Request 无法处理请求,因为格式有误或者不正确。Cannot process the request because it is malformed or incorrect.
401401 未经授权 (Unauthorized)Unauthorized 资源所需的身份验证信息缺少或无效。Required authentication information is either missing or not valid for the resource.
403403 Forbidden 禁止访问 (Forbidden)Forbidden 对所需资源的访问遭拒。用户权限可能不足。Access is denied to the requested resource. The user might not have enough permission.

重要说明: 如果向资源应用了条件访问策略,可能会返回 HTTP 403 禁止错误 (error=insufficent_claims)。Important: If conditional access policies are applied to a resource, a HTTP 403; Forbidden error=insufficent_claims may be returned. 有关 Microsoft Graph 和条件访问的详细信息,请参阅 Azure Active Directory 条件性访问开发人员指南For more details on Microsoft Graph and conditional access see Developer Guidance for Azure Active Directory Conditional Access
404404 errors 未找到 (Not Found)Not Found 所请求的资源不存在。The requested resource doesn’t exist.
405405 方法不允许 (Method Not Allowed)Method Not Allowed 请求中的 HTTP 方法在资源上不允许。The HTTP method in the request is not allowed on the resource.
406406 不接受 (Not Acceptable)Not Acceptable 该服务不支持“Accept”标头中请求的格式。This service doesn’t support the format requested in the Accept header.
409409 冲突 (Conflict)Conflict 当前状态与请求预期的状态的冲突。例如,指定的父文件夹可能不存在。The current state conflicts with what the request expects. For example, the specified parent folder might not exist.
4104.1.0 不存在 (Gone)Gone 所请求的资源在服务器不再可用。The requested resource is no longer available at the server.
4114.11 需要长度 (Length Required)Length Required 请求上需要 Content-Length 标头。A Content-Length header is required on the request.
4124.12 前提条件不满足 (Precondition Failed)Precondition Failed 请求中提供的前提条件(例如“If-Match”标头)与资源的当前状态不匹配。A precondition provided in the request (such as an if-match header) does not match the resource's current state.
4134.13 请求实体太大 (Request Entity Too Large)Request Entity Too Large 请求的大小超出最大限制。The request size exceeds the maximum limit.
4154.15 媒体类型不受支持 (Unsupported Media Type)Unsupported Media Type 请求的内容类型的格式不受服务支持。The content type of the request is a format that is not supported by the service.
4164.16 请求的范围不满足 (Requested Range Not Satisfiable)Requested Range Not Satisfiable 指定的字节范围无效或不可用。The specified byte range is invalid or unavailable.
422422 实体无法处理 (Unprocessable Entity)Unprocessable Entity 无法处理请求,因为语义上不正确。Cannot process the request because it is semantically incorrect.
423423 已锁定Locked 正在访问的资源被锁定。The resource that is being accessed is locked.
429429: 请求过多 (Too Many Requests)Too Many Requests 客户端应用程序已被限制,经过一段时间之后再尝试重复的请求。Client application has been throttled and should not attempt to repeat the request until an amount of time has elapsed.
500-500% 内部服务器错误 (Internal Server Error)Internal Server Error 处理请求时出现内部服务器错误。There was an internal server error while processing the request.
501501 未实现 (Not Implemented)Not Implemented 所请求的功能未实现。The requested feature isn’t implemented.
503503 服务不可用Service Unavailable 服务暂时无法维护或过载。你可以在延迟后重复该请求,其长度可以在 Retry-After 标头中指定。The service is temporarily unavailable for maintenance or is overloaded. You may repeat the request after a delay, the length of which may be specified in a Retry-After header.
504504 网关超时Gateway Timeout 服务器在充当代理时,没有收到它在尝试完成请求时需要访问的来自上游服务器的及时响应。可能会与 503 错误同时出现。The server, while acting as a proxy, did not receive a timely response from the upstream server it needed to access in attempting to complete the request. May occur together with 503.
507507 存储不足 (Insufficient Storage)Insufficient Storage 已达到最大存储配额。The maximum storage quota has been reached.
509509 超出带宽限制 (Bandwidth Limit Exceeded)Bandwidth Limit Exceeded 您的应用因超出最大带宽上限而被限制。应用可以在等待一段时间之后再重试该请求。Your app has been throttled for exceeding the maximum bandwidth cap. Your app can retry the request again after more time has elapsed.

错误响应是单个 JSON 对象,包含名为“error”的单个属性。此对象包括错误的所有详细信息。除了 HTTP 状态代码外,还可以使用此处返回的信息,或者使用此信息替代 HTTP 状态代码。以下是完整的 JSON 错误正文示例。The error response is a single JSON object that contains a single property named error. This object includes all the details of the error. You can use the information returned here instead of or in addition to the HTTP status code. The following is an example of a full JSON error body.

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

错误的资源类型Error resource type

只要处理请求的过程中出现错误,就会返回错误资源。The error resource is returned whenever an error occurs in the processing of a request.

错误响应遵循错误响应 OData v4 规范中的定义。Error responses follow the definition in the OData v4 specification for error responses.

JSON 表示形式JSON representation

错误资源包括以下资源:The error resource is composed of these resources:

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

odata.error 资源类型odata.error resource type

错误响应内是错误资源,其中包括以下属性:Inside the error response is an error resource that includes the following properties:

{
  "code": "string",
  "message": "string",
  "innererror": { "@odata.type": "odata.error" }
}
属性名称Property name Value 说明\Description\
codecode stringstring 发生的错误的错误代码字符串An error code string for the error that occured
messagemessage stringstring 关于发生的错误的开发人员就绪消息。这不应直接显示给用户。A developer ready message about the error that occured. This should not be displayed to the user directly.
innererrorinnererror error objecterror object 可选。可能比顶级错误更具体的其他错误对象。Optional. Additional error objects that may be more specific than the top level error.

代码属性Code property

code 属性包含下列可能值之一。您的应用应做好准备处理任意这些错误。The code property contains one of the following possible values. Your apps should be prepared to handle any one of these errors.

代码Code 说明Description
accessDeniedaccessDenied 调用方没有执行该操作的权限。The caller doesn't have permission to perform the action.
activityLimitReachedactivityLimitReached 应用或用户已被限制。The app or user has been throttled.
generalExceptiongeneralException 发生未指定错误。An unspecified error has occurred.
invalidRangeinvalidRange 指定的字节范围无效或不可用。The specified byte range is invalid or unavailable.
invalidRequestinvalidRequest 该请求格式有误或不正确。The request is malformed or incorrect.
itemNotFounditemNotFound 找不到资源。The resource could not be found.
malwareDetectedmalwareDetected 所请求的资源中检测到恶意软件。Malware was detected in the requested resource.
nameAlreadyExistsnameAlreadyExists 指定的项目名称已存在。The specified item name already exists.
notAllowednotAllowed 系统不允许执行此操作。The action is not allowed by the system.
notSupportednotSupported 系统不支持该请求。The request is not supported by the system.
resourceModifiedresourceModified 正在更新的资源自上次调用方读取时已进行了更改,通常是 eTag 不匹配。The resource being updated has changed since the caller last read it, usually an eTag mismatch.
resyncRequiredresyncRequired 增量令牌将不再有效,并且应用必须重置同步状态。The delta token is no longer valid, and the app must reset the sync state.
serviceNotAvailableserviceNotAvailable 服务不可用。过段时间后再次尝试请求。可能会有 Retry-After 标头。The service is not available. Try the request again after a delay. There may be a Retry-After header.
quotaLimitReachedquotaLimitReached 用户已达到其配额限制。The user has reached their quota limit.
unauthenticatedunauthenticated 调用方未进行身份验证。The caller is not authenticated.

innererror 对象可能以递归方式包含更多 innererror 对象,其中具有其他更多具体的错误代码。处理错误时,应用应遍历所有可用错误代码并使用它们认为最详细的错误代码。在本页底部列出了一些更详细的代码。The innererror object might recursively contain more innererror objects with additional, more specific error codes. When handling an error, apps should loop through all the error codes available and use the most detailed one that they understand. Some of the more detailed codes are listed at the bottom of this page.

若要验证某个错误对象是否是你想要的错误,你必须遍历 innererror 对象,查找你想要的错误代码。例如:To verify that an error object is an error you are expecting, you must loop over the innererror objects, looking for the error codes you expect. For example:

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

有关介绍如何正确处理错误的示例,请参阅 错误代码处理For an example that shows how to properly handle errors, see Error Code Handling.

根处的 message 属性包含供开发人员阅读的错误消息。错误消息未本地化,并且不应直接向用户显示。处理错误时,代码不应关闭 message 值,因为它们随时会更改,并且它们通常包含特定于失败请求的动态信息。只应针对 code 属性中返回的错误代码进行编码。The message property at the root contains an error message intended for the developer to read. Error messages are not localized and shouldn't be displayed directly to the user. When handling errors, your code should not key off of message values because they can change at any time, and they often contain dynamic information specific to the failed request. You should only code against error codes returned in code properties.

详细的错误代码Detailed error codes

以下是你的应用可能会在嵌套的 innererror 对象中遇到的一些其他错误。应用不需要处理这些错误,但如果它们选择,也可以处理。服务可能会随时添加新的错误代码或者停止返回的旧代码,因此所有应用都能够处理 基本错误代码 非常重要。The following are some additional errors that your app might encounter within the nested innererror objects. Apps are not required to handle these, but can if they choose. The service might add new error codes or stop returning old ones at any time, so it is important that all apps be able to handle the basic error codes.

代码Code 说明Description
accessRestrictedaccessRestricted 访问仅限于该项目的所有者。Access restricted to the item's owner.
cannotSnapshotTreecannotSnapshotTree 未能获取一致的增量快照。请稍后重试。Failed to get a consistent delta snapshot. Try again later.
childItemCountExceededchildItemCountExceeded 已达到最大子项目数限制。Max limit on the number of child items was reached.
entityTagDoesNotMatchentityTagDoesNotMatch ETag 与当前项目的值不匹配。ETag does not match the current item's value.
fragmentLengthMismatchfragmentLengthMismatch 为此片段声明的总大小与上载会话的大小不同。Declared total size for this fragment is different from that of the upload session.
fragmentOutOfOrderfragmentOutOfOrder 已上载的片段无序。Uploaded fragment is out of order.
fragmentOverlapfragmentOverlap 上载的片段与现有数据重叠。Uploaded fragment overlaps with existing data.
invalidAcceptTypeinvalidAcceptType 接受类型无效。Invalid accept type.
invalidParameterFormatinvalidParameterFormat 参数格式无效。Invalid parameter format.
invalidPathinvalidPath 名称包含无效字符。Name contains invalid characters.
invalidQueryOptioninvalidQueryOption 查询选项无效。Invalid query option.
invalidStartIndexinvalidStartIndex 开始索引无效。Invalid start index.
lockMismatchlockMismatch 锁定令牌与现有锁定不匹配。Lock token does not match existing lock.
lockNotFoundOrAlreadyExpiredlockNotFoundOrAlreadyExpired 该项目上目前没有未过期的锁定。There is currently no unexpired lock on the item.
lockOwnerMismatchlockOwnerMismatch 锁定所有者 ID 与提供的 ID 不匹配。Lock Owner ID does not match provided ID.
malformedEntityTagmalformedEntityTag ETag 标头格式不正确。ETags 必须是带引号的字符串。ETag header is malformed. ETags must be quoted strings.
maxDocumentCountExceededmaxDocumentCountExceeded 已达到最大文档数量限制。Max limit on number of Documents is reached.
maxFileSizeExceededmaxFileSizeExceeded 已超出最大文件大小。Max file size exceeded.
maxFolderCountExceededmaxFolderCountExceeded 已达到最大文件夹数量限制。Max limit on number of Folders is reached.
maxFragmentLengthExceededmaxFragmentLengthExceeded 已超出最大文件大小。Max file size exceeded.
maxItemCountExceededmaxItemCountExceeded 已达到最大项目数量限制。Max limit on number of Items is reached.
maxQueryLengthExceededmaxQueryLengthExceeded 已超出最大查询长度。Max query length exceeded.
maxStreamSizeExceededmaxStreamSizeExceeded 已达到最大流大小。Maximum stream size exceeded.
parameterIsTooLongparameterIsTooLong 参数超出最大长度。Parameter Exceeds Maximum Length.
parameterIsTooSmallparameterIsTooSmall 参数小于最小值。Parameter is smaller then minimum value.
pathIsTooLongpathIsTooLong 路径超出最大长度。Path exceeds maximum length.
pathTooDeeppathTooDeep 已达到文件夹层次结构深度限制。Folder hierarchy depth limit reached.
propertyNotUpdateablepropertyNotUpdateable 属性无法更新。Property not updateable.
resyncApplyDifferencesresyncApplyDifferences 需要重新同步。如果您确定上次同步时服务与您的本地更改保持同步,则请将任意本地项目替换为服务器的版本(包括删除)。上载服务器并不清楚的任意本地更改。Resync required. Replace any local items with the server's version (including deletes) if you're sure that the service was up to date with your local changes when you last sync'd. Upload any local changes that the server doesn't know about.
resyncRequiredresyncRequired 需要重新同步。Resync is required.
resyncUploadDifferencesresyncUploadDifferences 需要重新同步。上载服务未返回的任意本地项目,并上载与服务器版本不同的任意文件(如果不知道哪个是最新的,就请保留两份)。Resync required. Upload any local items that the service did not return, and upload any files that differ from the server's version (keeping both copies if you're not sure which one is more up-to-date).
serviceNotAvailableserviceNotAvailable 服务器无法处理当前的请求。The server is unable to process the current request.
serviceReadOnlyserviceReadOnly 资源暂时是只读的。Resource is temporarily read-only.
throttledRequestthrottledRequest 请求过多。Too many requests.
tooManyResultsRequestedtooManyResultsRequested 请求的结果过多。Too many results requested.
tooManyTermsInQuerytooManyTermsInQuery 查询中的术语过多。Too many terms in the query.
totalAffectedItemCountExceededtotalAffectedItemCountExceeded 因为受影响的项目数量超出阈值,所以不允许该操作。Operation is not allowed because the number of affected items exceeds threshold.
truncationNotAllowedtruncationNotAllowed 不允许数据截断。Data truncation is not allowed.
uploadSessionFaileduploadSessionFailed 上载会话失败。Upload session failed.
uploadSessionIncompleteuploadSessionIncomplete 上载会话未完成。Upload session incomplete.
uploadSessionNotFounduploadSessionNotFound 上载会话未找到。Upload session not found.
virusSuspiciousvirusSuspicious 此文档可疑,可能存在病毒。This document is suspicious and may have a virus.
zeroOrFewerResultsRequestedzeroOrFewerResultsRequested 请求的结果为零或更少。Zero or fewer results requested.