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 错误，在找到已知的第二级错误代码时，请按照相应的说明进行操作;否则，应直接重新创建会话。

相关内容

• 使用 Excel REST API