常见的错误响应和代码
OneDrive API 中的错误使用标准 HTTP 状态代码和 JSON 错误响应对象进行返回。 应使用以下 HTTP 状态代码。
| 状态代码 | 状态消息 | 说明 |
|---|---|---|
| 400 | 错误的请求 (Bad Request) | 无法处理请求，因为格式有误或者不正确。 |
| 401 | 未经授权 (Unauthorized) | 资源所需的身份验证信息缺少或无效。 |
| 403 | 禁止访问 | 对于请求的资源，访问被拒绝。 用户可能没有足够的权限。 |
| 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) | 无法处理请求，因为语义上不正确。 |
| 429 | 请求过多 (Too Many Requests) | 客户端应用程序已被限制，经过一段时间之后再尝试重复的请求。 |
| 500 | 内部服务器错误 (Internal Server Error) | 处理请求时出现内部服务器错误。 |
| 501 | 未实现 (Not Implemented) | 所请求的功能未实现。 |
| 503 | 服务不可用 | 该服务暂时不可用。 可以过段时间之后再重复该请求。 可能会有 Retry-After 标头。 |
| 507 | 存储不足 (Insufficient Storage) | 已达到最大存储配额。 |
| 509 | 超出带宽限制 | 您的应用因超出最大带宽上限而被限制。 应用可以在等待一段时间之后再重试该请求。 |
错误响应是单个 JSON 对象，包含名为“错误”的单个属性。 此对象包括错误的所有详细信息。 除了返回的 HTTP 状态代码外，您还可以使用此处返回的信息，或者使用此信息替代 HTTP 状态代码。 下面是完整的 JSON 错误正文示例。
{
"error": {
"code": "invalidRange",
"message": "Uploaded fragment overlaps with existing data.",
"innererror": {
"code": "fragmentOverlap"
}
}
}
code 属性
code 属性有 15 个可取值。 应用应做好处理其中任一错误的准备。
| 代码 | 说明 |
|---|---|
| accessDenied | 调用方没有执行该操作的权限。 |
| activityLimitReached | 应用或用户已被限制。 |
| generalException | 发生未指定错误。 |
| invalidRange | 指定的字节范围无效或不可用。 |
| invalidRequest | 该请求格式有误或不正确。 |
| itemNotFound | 找不到资源。 |
| malwareDetected | 所请求的资源中检测到恶意软件。 |
| nameAlreadyExists | 指定的项目名称已存在。 |
| notAllowed | 系统不允许执行此操作。 |
| notSupported | 系统不支持该请求。 |
| resourceModified | 正在更新的资源自上次调用方读取时已进行了更改，通常是 eTag 不匹配。 |
| resyncRequired | 增量令牌将不再有效，并且应用必须重置同步状态。 |
| serviceNotAvailable | 服务不可用。 过段时间后再次尝试请求。 可能会有 Retry-After 标头。 |
| 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;
}
有关正确处理错误的完整示例，请参阅 OneDrive 错误代码处理。
根处的 message 属性包含供开发人员阅读的错误消息。 错误消息未本地化，并且不应直接向用户显示。 处理错误时，你的代码不能切断 message 值，因为它们随时会更改，并且它们通常包含 特定于失败请求的动态信息。 只应针对 code 属性中返回的错误代码进行编码。
若要详细了解错误响应中返回的资源，请参阅 Error 资源类型主题。
详细的错误代码
下面是你的应用可能会在嵌套的 innererror 对象中遇到的一些其他错误。 应用不需要处理这些错误，但如果选择处理，也可以这样做。 服务可能会随时添加新的错误代码或停止返回旧的错误代码，因此所有应用务必要能够处理上述 15 个基本错误代码。
| 代码 | 说明 |
|---|---|
| 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 | 属性无法更新。 |
| resyncApplyDifferences | 需要重新同步。 如果您确定上次同步时服务与您的本地更改保持同步，则请将任意本地项目替换为服务器的版本（包括删除）。 上载服务器并不清楚的任意本地更改。 |
| resyncRequired | 需要重新同步。 |
| resyncUploadDifferences | 需要重新同步。 上载服务未返回的任意本地项目，并上载与服务器版本不同的任意文件（如果不知道哪个是最新的，请保留两份）。 |
| serviceNotAvailable | 服务器无法处理当前的请求。 |
| serviceReadOnly | 资源暂时是只读的。 |
| throttledRequest | 请求过多。 |
| tooManyResultsRequested | 请求的结果过多。 |
| tooManyTermsInQuery | 查询中的术语过多。 |
| totalAffectedItemCountExceeded | 因为受影响的项目数量超出阈值，所以不允许该操作。 |
| truncationNotAllowed | 不允许数据截断。 |
| uploadSessionFailed | 上载会话失败。 |
| uploadSessionIncomplete | 上载会话未完成。 |
| uploadSessionNotFound | 上载会话未找到。 |
| virusSuspicious | 此文档可疑，可能存在病毒。 |
| zeroOrFewerResultsRequested | 请求的结果为零或更少。 |