Excel API 的错误处理
本文提供有关处理通过 API 发送的请求失败时 Microsoft Graph 中 Excel API 返回的错误的一般说明和建议。
Microsoft Graph 中的 Excel API 返回两种类型的错误。 一个是常规错误响应,如下所示。
HTTP/1.1 <HTTP status code>
Content-type: application/json
Retry-After: <Cooldown duration in seconds> (optional)
{
"error": <Error object>
}
第二种模式来自长时间运行的操作模式,该模式可以在响应正文中返回 200 OK
HTTP 状态代码和 failed
操作状态,如以下示例所示。
HTTP/1.1 200 OK
Content-type: application/json
{
"status": "failed",
"error": <Error object>
}
对于这两个错误响应,error 对象具有以下结构。
备注
错误响应遵循错误响应 OData v4 规范中的定义。
{
"code": "string",
"message": "string",
"innerError": { "@odata.type": "odata.error" }
}
innerError 对象可能以递归方式包含更多的 innerError 对象,并带有其他更具体的错误代码。 例如,错误对象可能会在第二级错误代码和消息中包含更详细的错误信息,如下所示。
{
"code": "Top-level error code",
"message": "Top-level error message",
"innerError": {
"code": "Second-level error code",
"message": "Second-level error message",
"innerError": { "@odata.type": "odata.error" }
}
}
Microsoft Graph 客户端应使用以下步骤来处理 Excel API 发生的错误。
在处理错误之前,第一步是确定错误响应来自长时间运行的操作模式还是常规模式。 长时间运行的操作错误将在响应正文中返回 200 OK
HTTP 状态代码和 failed
操作状态。 常规错误响应将返回相应的 HTTP 错误状态代码。
对于长时间运行的操作模式和常规模式,客户端应首先分析所需的二级错误代码,并根据说明进行处理。 (可选)客户端还可以处理其他二级错误代码,或选择回退到 顶级错误代码 或 状态代码。
错误代码不区分大小写。
下表列出了 Microsoft Graph 客户端应处理的必需第二级错误代码的说明。 该服务可能随时添加新错误代码。
代码 | 说明 |
---|---|
accessConflict |
失败的请求与其他访问工作簿的客户端冲突 (例如,另一个客户端已锁定工作簿进行编辑) 。 在冲突解决之前,Microsoft Graph 客户端不会重新发送失败的请求。 最终用户可以选择使用 Excel Online 手动执行相同的操作,以获取有关冲突的更多详细信息。 |
badRequestUncategorized |
在失败的请求中发现了未指定的错误。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
conflictUncategorized |
失败的请求与某些服务器状态冲突。 在冲突解决之前,Microsoft Graph 客户端不会重新发送失败的请求。 最终用户可以选择使用 Excel Online 手动执行相同的操作,以获取有关冲突的更多详细信息。 |
forbiddenUncategorized |
不允许失败的请求。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 最终用户可以选择使用 Excel Online 手动执行相同的操作,以获取有关限制的更多详细信息。 |
gatewayTimeoutUncategorized |
服务无法在时限内完成请求。 |
internalServerErrorUncategorized |
发生未指定错误。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 如果在失败的请求中指定了会话,则也不应进一步访问该会话。 |
invalidSessionAccessConflict |
请求中指定的会话无效,因为与访问工作簿的其他客户端发生冲突 (例如,另一个客户端已锁定工作簿进行编辑) 。 不应进一步访问失败请求中指定的会话。 在冲突解决之前,不应使用相同的 createSession 请求重新创建会话。 使用其他 createSession 请求重新创建会话可能会成功,也可能不成功。 最终用户可以选择使用 Excel Online 手动执行相同的操作,以获取有关冲突的更多详细信息。 |
invalidSessionAuthentication |
由于身份验证错误,请求中指定的会话无效。 不应进一步访问失败请求中指定的会话。 在提供适当的身份验证信息之前,不应使用相同的 createSession 请求重新创建会话。 |
invalidSessionNotFound |
请求中指定的会话无效,因为找不到工作簿。 不应进一步访问失败请求中指定的会话。 不应使用相同的 createSession 请求重新创建会话。 |
invalidSessionReCreatable |
请求中指定的会话不存在,或者由于暂时性错误而无效。 Microsoft Graph 客户端可以尝试重新创建会话并恢复工作。 不应进一步访问失败请求中指定的会话。 |
invalidSessionRestricted |
由于服务配置或限制,请求中指定的会话无效。 不应进一步访问失败请求中指定的会话。 在阻止请求的限制或配置发生更改之前,不应使用相同的 createSession 请求重新创建会话。 使用其他 createSession 请求重新创建会话可能会成功,也可能不成功。 最终用户可以选择使用 Excel Online 手动执行相同的操作,以获取有关限制的更多详细信息。 |
invalidSessionUnexpected |
请求中指定的会话由于意外问题而无效。 不应进一步访问失败请求中指定的会话。 不应使用相同的 createSession 请求重新创建会话。 使用其他 createSession 请求重新创建会话可能会成功,也可能不成功。 |
invalidSessionUnsupportedWorkbook |
请求中指定的会话无效,因为工作簿包含不支持的功能或超出大小限制。 通常,不受支持的因素是由访问工作簿的另一个客户端引入的。 不应进一步访问失败请求中指定的会话。 在删除不受支持的因素之前,不应使用相同的 createSession 请求重新创建会话。 使用其他 createSession 请求重新创建会话可能会成功,也可能不成功。 最终用户可以选择使用 Excel Online 手动执行相同的操作,以获取不受支持的因素的更多详细信息,或者使用 Excel Desktop(可能支持工作簿)。 |
methodNotAllowedUncategorized |
资源上不允许使用请求中指定的 HTTP 方法。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
notFoundUncategorized |
找不到请求的资源。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
notImplementedUncategorized |
请求的功能当前未实现。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
payloadTooLargeUncategorized |
请求有效负载超出大小限制。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
serviceUnavailableUncategorized |
服务暂时不可用或已重载。 在指定的冷却持续时间过后,Microsoft Graph 客户端不会重新发送失败的请求。 |
tooManyRequestsUncategorized |
失败的请求超出了特定频率限制。 在指定的冷却持续时间过后,Microsoft Graph 客户端不会重新发送失败的请求。 有关减少限制的最佳做法,请参阅 减少限制错误。 |
transientFailure |
由于暂时性错误,请求失败。 在指定的冷却持续时间过后,Microsoft Graph 客户端不会重新发送失败的请求。 |
unauthorizedUncategorized |
资源所需的身份验证信息缺失或无效。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
unsupportedWorkbook |
请求失败。 工作簿包含不支持的功能或超出大小限制。 在删除不受支持的因素之前,Microsoft Graph 客户端不会重新发送失败的请求。 |
备注
对于常规模式,失败的请求定义为与响应对应的请求。 对于长时间运行的操作模式,失败的请求是触发失败操作的请求。
下表列出了可选的第二级错误代码的示例,包括每个错误代码的相应处理说明。 该服务可能随时添加新错误代码。
代码 | 说明 |
---|---|
accessDenied |
例如,无法执行请求的操作 (对锁定的单元格执行更改) 。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
filteredRangeConflict |
操作失败,因为它与筛选的范围冲突。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
generalException |
处理请求时发生内部错误。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
insertDeleteConflict |
尝试的插入或删除操作导致冲突。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 最终用户可以选择使用 Excel Online 手动执行相同的操作,以获取有关冲突的更多详细信息。 |
invalidArgument |
参数无效、缺失或格式不正确。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
invalidReference |
此引用对于当前操作无效。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
itemAlreadyExists |
所创建的资源已存在。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
itemNotFound |
所请求的资源不存在。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
methodNotAllowed |
资源上不允许使用请求中指定的 HTTP 方法。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
nonBlankCellOffSheet |
无法插入新单元格,因为它会将非空单元格从工作表的末尾推送。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 最终用户可以删除行或列,以便为要插入的内容腾出空间,然后重试。 |
rangeExceedsLimit |
区域中的单元格计数已超过支持的最大数目。 Microsoft Graph 客户端可以尝试发送范围较小的请求。 有关详细信息,请参阅 Office 外接程序的资源限制和性能优化。 |
requestAborted |
请求在运行时中止,这通常是由工作簿中的函数长时间计算引起的。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
unsupportedOperation |
不支持正在尝试的操作。 预计 Microsoft Graph 客户端不会重新发送失败的请求。 |
备注
对于常规模式,失败的请求定义为与响应对应的请求。 对于长时间运行的操作模式,失败的请求是触发失败操作的请求。
如果找不到任何已知的第二级错误代码,则应按照针对顶级错误提供的说明进行操作。 顶级错误代码绑定到状态代码,你可以根据相应的状态代码采取措施。 有关顶级错误代码和消息的详细信息,请参阅 错误代码和消息。
对于常规模式,如果找不到任何已知的第二级错误代码或顶级错误代码,则应根据 HTTP 状态代码采取措施。
对于常规模式中的某些响应,可以通过标头提供 Retry-After
恢复冷却持续时间(以秒为单位)。 当存在恢复冷却持续时间时,Microsoft Graph 客户端预计不会在指定的持续时间之前发送任何后续请求。 有关标头和限制的 Retry-After
最佳做法,请参阅 减少限制错误。
响应中未在上述步骤中使用的所有内容仅用于诊断目的, () 的消息字段中包含字符串。 我们不建议依赖这些内容,因为它们可能会在未通知的情况下更改。
对于 会话请求,如果遇到 502/badGateway
或 503/serviceUnavailable
错误,在找到已知的第二级错误代码时,请按照相应的说明进行操作;否则,应直接重新创建会话。