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 发生的错误。
1.确定它是否是长时间运行的操作错误
在处理错误之前，第一步是确定错误响应来自长时间运行的操作模式还是常规模式。 长时间运行的操作错误将在响应正文中返回 200 OK HTTP 状态代码和 failed 操作状态。 常规错误响应将返回相应的 HTTP 错误状态代码。
2. 分析二级错误代码
对于长时间运行的操作模式和常规模式，客户端应首先分析所需的二级错误代码，并根据说明进行处理。 （可选）客户端还可以处理其他二级错误代码，或选择回退到 顶级错误代码 或 状态代码。
错误代码不区分大小写。
必需的二级错误代码
下表列出了 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 客户端不会重新发送失败的请求。 |
注意
对于常规模式，失败的请求定义为与响应对应的请求。 对于长时间运行的操作模式，失败的请求是触发失败操作的请求。
3.分析顶级错误代码
如果找不到任何已知的第二级错误代码，则应按照针对顶级错误提供的说明进行操作。 顶级错误代码绑定到状态代码，你可以根据相应的状态代码采取措施。 有关顶级错误代码和消息的详细信息，请参阅 错误代码和消息。
4.分析状态代码
对于常规模式，如果找不到任何已知的第二级错误代码或顶级错误代码，则应根据 HTTP 状态代码采取措施。
5. 故障恢复冷却时间
对于常规模式中的某些响应，可以通过标头提供 Retry-After 恢复冷却持续时间（以秒为单位）。 当存在恢复冷却持续时间时，Microsoft Graph 客户端预计不会在指定的持续时间之前发送任何后续请求。 有关标头和限制的 Retry-After 最佳做法，请参阅 减少限制错误。
诊断信息
响应中未在上述步骤中使用的所有内容仅用于诊断目的， () 的消息字段中包含字符串。 我们不建议依赖这些内容，因为它们可能会在未通知的情况下更改。
特殊案例处理
对于 会话请求，如果遇到 502/badGateway 或 503/serviceUnavailable 错误，在找到已知的第二级错误代码时，请按照相应的说明进行操作;否则，应直接重新创建会话。