Microsoft Graph 中 Excel API 的错误处理Error handling for Excel APIs in Microsoft Graph

本文提供有关处理通过 API 发送的请求失败时 Microsoft Graph 中的 Excel API 返回的错误的一般说明和建议。This article provides general instructions and suggestions for handling errors that are returned by the Excel APIs in Microsoft Graph when a request sent through the API fails.

错误响应的类型Types of error responses

Microsoft Graph 中的 Excel API 返回两种类型的错误。Excel APIs in Microsoft Graph return two types of errors. 一种是常规错误响应,如下所示。One is the regular error response, which looks like the following.

HTTP/1.1 <HTTP status code>
Content-type: application/json

{
  "error": <Error object>
}

第二个来自长时间运行的操作模式,该模式可在响应正文中返回 HTTP 状态代码和操作 200 OK failed 状态,如以下示例所示。The second is from the long-running operation pattern, which can return a 200 OK HTTP status code and failed operation status in response body, as in the following example.

HTTP/1.1 200 OK
Content-type: application/json

{
  "status": "failed",
  "error": <Error object>
}

对于这两种错误响应,错误对象具有以下结构。For both of these error responses, the error object has the following structure.

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

{
  "code": "string",
  "message": "string",
  "innerError": { "@odata.type": "odata.error" }
}

innerError 对象可能以递归方式包含更多 innerError 对象,其中具有其他更多具体的错误代码。The innerError object might recursively contain more innerError objects with additional, more specific error codes. 例如,错误对象可能包含第二级错误代码和消息中更详细的错误信息,如下所示。For example, the error object might contain more detailed error information in the second-level error code and message, as shown.

{
  "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" }
  }
}

处理错误响应的步骤Steps to handle error responses

Microsoft Graph 客户端可以使用以下步骤来处理 Excel API 发生的错误。Microsoft Graph clients can use the following steps to handle errors that occur with Excel APIs.

1. 确定它是否是长时间运行的操作错误1. Determine whether it is a long-running operation error

在处理错误之前,第一步是确定错误响应来自长时间运行的操作模式还是常规模式。Before handling an error, the first step is to determine whether the error response is from a long-running operation pattern or a regular pattern. 长时间运行的操作错误将在响应正文中返回 200 OK HTTP failed 状态代码和操作状态。A long-running operation error will return a 200 OK HTTP status code and failed operation status in response body. 常规错误响应将返回相应的 HTTP 错误状态代码。A regular error response will return a corresponding HTTP error status code.

2. 分析二级错误代码2. Parse second-level error code

对于长时间运行的操作模式和常规模式,我们建议您首先按照说明处理二级错误。For both the long-running operation pattern and the regular pattern, we recommend that you first follow the instructions for second-level errors. 错误代码不区分大小写。The error code is case insensitive. 下表列出了某些错误的说明。The following table lists instructions for some of the errors. 该服务可能随时添加新的错误代码。The service might add new error codes at any time.

代码Code 说明Instructions
accessConflictaccessConflict 失败的请求与其他访问工作簿的客户端冲突 (例如,另一个客户端锁定工作簿进行编辑) 。The failed request conflicts with other clients accessing the workbook (for example, another client has locked the workbook for edit). 在解决冲突之前,Microsoft Graph 客户端不会重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request until the conflict is resolved. 最终用户可以选择使用 Excel Online 手动执行相同的操作,获取有关冲突的更多详细信息。An end user can choose to manually perform the same operations with Excel Online to get more details about the conflict.
accessDeniedaccessDenied 不能执行请求的操作 (例如,对锁定的单元格执行) 。You cannot perform the requested operation (for example, performing changes to locked cells). Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
badRequestUncategorizedbadRequestUncategorized 在失败的请求中发现未指定的错误。An unspecified error is found in the failed request. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
conflictUncategorizedconflictUncategorized 失败的请求与某些服务器状态冲突。The failed request conflicts with certain server state. 在解决冲突之前,Microsoft Graph 客户端不会重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request until the conflict is resolved. 最终用户可以选择使用 Excel Online 手动执行相同的操作,获取有关冲突的更多详细信息。An end user can choose to manually perform the same operations with Excel Online to get more details about the conflict.
filteredRangeConflictfilteredRangeConflict 操作失败,因为它与筛选出的范围冲突。The operation failed because it conflicts with a filtered range. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
forbiddenUncategorizedforbiddenUncategorized 不允许失败的请求。The failed request is not allowed. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request. 最终用户可以选择使用 Excel Online 手动执行相同的操作,获取有关限制的更多详细信息。An end user can choose to manually perform the same operations with Excel Online to get more details about the restrictions.
gatewayTimeoutUncategorizedgatewayTimeoutUncategorized 服务无法在此时间限制内完成请求。The service wasn’t able to complete the request within the time limit.
generalExceptiongeneralException 处理请求时出现内部错误。An internal error occurred while processing the request. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
insertDeleteConflictinsertDeleteConflict 尝试的插入或删除操作导致冲突。The insert or delete operation attempted resulted in a conflict. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
internalServerErrorUncategorizedinternalServerErrorUncategorized 发生未指定错误。An unspecified error has occurred. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request. 如果在失败的请求中指定了会话,则不需要进一步访问会话。If a session is specified in the failed request, further access to the session is not expected either.
invalidArgumentinvalidArgument 自变量无效、缺少或格式不正确。The argument is invalid or missing or has an incorrect format. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
invalidReferenceinvalidReference 此引用对于当前操作无效。This reference is not valid for the current operation. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
invalidSessionAccessConflictinvalidSessionAccessConflict 由于与其他访问工作簿的客户端发生冲突,请求中指定的会话无效 (例如,另一个客户端锁定了工作簿进行编辑) 。The session specified in the request is invalid due to conflicts with other clients that are accessing the workbook (for example, another client has locked the workbook for edit). 不应进一步访问失败请求中指定的会话。Further access to the session specified in the failed request is not expected. 在解决冲突之前,不需要重新创建具有相同 createSession 请求的会话。Recreating sessions with the same createSession request is not expected until the conflict is resolved. 使用不同的 createSession 请求重新创建会话可能会成功,也可能失败。Recreating sessions with a different createSession request might or might not succeed. 最终用户可以选择使用 Excel Online 手动执行相同的操作,获取有关冲突的更多详细信息。An end user can choose to manually perform the same operations with Excel Online to get more details about the conflict.
invalidSessionAuthenticationinvalidSessionAuthentication 由于身份验证错误,请求中指定的会话无效。The session specified in the request is invalid due to an authentication error. 不应进一步访问失败请求中指定的会话。Further access to the session specified in the failed request is not expected. 在提供适当的身份验证信息之前,不应使用相同的 createSession 请求重新创建会话。Recreating sessions with the same createSession request is not expected until appropriate authentication information is provided.
invalidSessionNotFoundinvalidSessionNotFound 请求中指定的会话无效,因为找不到工作簿。The session specified in the request is invalid because the workbook can’t be found. 不应进一步访问失败请求中指定的会话。Further access to the session specified in the failed request is not expected. 不需要使用相同的 createSession 请求重新创建会话。Recreating sessions with the same createSession request is not expected.
invalidSessionReCreatableinvalidSessionReCreatable 请求中指定的会话不存在或由于暂时性错误而无效。The session specified in the request does not exist or is invalid due to a transient error. Microsoft Graph 客户端可以尝试重新创建会话并恢复工作。The Microsoft Graph client can try to recreate a session and resume the work. 不应进一步访问失败请求中指定的会话。Further access to the session specified in the failed request is not expected.
invalidSessionRestrictedinvalidSessionRestricted 由于服务配置或限制,请求中指定的会话无效。The session specified in the request is invalid due to service configurations or restrictions. 不应进一步访问失败请求中指定的会话。Further access to the session specified in the failed request is not expected. 在阻止请求的限制或配置更改之前,不需要重新创建具有相同 createSession 请求的会话。Recreating sessions with the same createSession request is not expected until the restrictions or configurations blocking the request changes. 使用不同的 createSession 请求重新创建会话可能会成功,也可能失败。Recreating sessions with a different createSession request might or might not succeed. 最终用户可以选择使用 Excel Online 手动执行相同的操作,获取限制的更多详细信息。An end user can choose to manually perform the same operations with Excel Online to get more details of the restrictions.
invalidSessionUnexpectedinvalidSessionUnexpected 由于意外问题,请求中指定的会话无效。The session specified in the request is invalid due to an unexpected issue. 不应进一步访问失败请求中指定的会话。Further access to the session specified in the failed request is not expected. 不需要使用相同的 createSession 请求重新创建会话。Recreating sessions with the same createSession request is not expected. 使用不同的 createSession 请求重新创建会话可能会成功,也可能失败。Recreating sessions with a different createSession request might or might not succeed.
invalidSessionUnsupportedWorkbookinvalidSessionUnsupportedWorkbook 请求中指定的会话无效,因为工作簿包含不受支持的功能或超出大小限制。The session specified in the request is invalid because the workbook contains unsupported features or exceeds the size limit. 通常,不受支持的因素由访问工作簿的另一个客户端引入。Usually the unsupported factors are introduced by another client accessing the workbook. 不应进一步访问失败请求中指定的会话。Further access to the session specified in the failed request is not expected. 在删除不受支持的因素之前,不需要重新创建具有相同 createSession 请求的会话。Recreating sessions with the same createSession request is not expected until the unsupported factors are removed. 使用不同的 createSession 请求重新创建会话可能会成功,也可能失败。Recreating sessions with a different createSession request might or might not succeed. 最终用户可以选择使用 Excel Online 手动执行相同的操作,获取不受支持因素的更多详细信息,也可以选择使用 Excel 桌面(其中工作簿可能受支持)。An end user can choose to manually perform the same operations with Excel Online to get more details of the unsupported factors, or with Excel Desktop where the workbook might be supported.
itemAlreadyExistsitemAlreadyExists 所创建的资源已存在。The resource being created already exists. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
itemNotFounditemNotFound 所请求的资源不存在。The requested resource doesn't exist. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
methodNotAllowedmethodNotAllowed 资源上不允许使用请求中指定的 HTTP 方法。The HTTP method specified in the request is not allowed on the resource. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
methodNotAllowedUncategorizedmethodNotAllowedUncategorized 资源上不允许使用请求中指定的 HTTP 方法。The HTTP method specified in the request is not allowed on the resource. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
nonBlankCellOffSheetnonBlankCellOffSheet 无法插入新单元格,因为它会将非空单元格推送到工作表的末尾。Can't insert new cells because it would push non-empty cells off the end of the worksheet. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
notFoundUncategorizednotFoundUncategorized 找不到请求的资源。The requested resource cannot be found. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
notImplementedUncategorizednotImplementedUncategorized 请求的功能当前未实现。The requested feature is not currently implemented. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
payloadTooLargeUncategorizedpayloadTooLargeUncategorized 请求有效负载超过大小限制。The request payload exceeds the size limit. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
rangeExceedsLimitrangeExceedsLimit 范围中的单元格计数已超出支持的最大数。The cell count in range has exceeded the maximum supported number. Microsoft Graph 客户端可以尝试发送范围较小的请求。The Microsoft Graph client can try to send a request with smaller range size.
requestAbortedrequestAborted 请求在运行期间中止,这通常是由工作簿中函数的长时间计算导致的。The request was aborted during run time, which was usually caused by long time calculation from functions in the workbook. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
serviceUnavailableUncategorizedserviceUnavailableUncategorized 服务暂时不可用或过载。The service is temporarily unavailable or is overloaded. Microsoft Graph 客户端不会重新发送失败的请求,直到指定的关闭持续时间过去。The Microsoft Graph client is not expected to resend the failed request until the specified cooldown duration passes.
tooManyRequestsUncategorizedtooManyRequestsUncategorized 失败的请求超出了某些频率限制。The failed request exceeds certain frequency limitation. Microsoft Graph 客户端不会重新发送失败的请求,直到指定的关闭持续时间过去。The Microsoft Graph client is not expected to resend the failed request until the specified cooldown duration passes.
transientFailuretransientFailure 由于暂时性错误,请求失败。The request failed due to a transient error. Microsoft Graph 客户端不会重新发送失败的请求,直到指定的关闭持续时间过去。The Microsoft Graph client is not expected to resend the failed request until the specified cooldown duration passes.
unauthorizedUncategorizedunauthorizedUncategorized 资源所需的身份验证信息缺失或无效。Required authentication information for the resource is either missing or invalid. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
unsupportedOperationunsupportedOperation 不支持正在尝试的操作。The operation being attempted is not supported. Microsoft Graph 客户端不应重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request.
unsupportedWorkbookunsupportedWorkbook 请求失败。The request failed. 工作簿包含不受支持的功能或超出大小限制。The workbook contains unsupported features or exceeds the size limit. 在删除不受支持的因素之前,Microsoft Graph 客户端不会重新发送失败的请求。The Microsoft Graph client is not expected to resend the failed request until the unsupported factors are removed.

注意: 对于常规模式,失败的请求定义为与响应对应的请求。Note: For the regular pattern, the failed request is defined as the request corresponding to the response. 对于长时间运行的操作模式,失败的请求是触发失败操作的请求。For the long-running operation pattern, the failed request is the one that triggers the failed operation.

3. 分析顶级错误代码3. Parse the top-level error code

如果找不到"详细错误代码"主题中列出的二级错误代码,我们建议您按照针对顶级错误提供的说明操作。If you can't find the second-level error code listed in the Detailed error codes topic, we recommend that you follow the instructions provided for top-level errors. 顶级错误代码绑定到状态代码,你可以根据相应的状态代码采取措施。The top-level error codes are bound to the status code and you can take action according to the corresponding status codes. 有关顶级错误代码和消息的详细信息,请参阅 错误代码For details about top-level error codes and messages, see Error codes.

4. 分析状态代码4. Parse the status code

如果您遇到的错误代码不在二级列表或顶级列表中,我们建议您根据 HTTP 状态代码采取措施。If the error code you encounter is not in the second-level list or the top-level list, we recommend that you take action according to the HTTP status code.

5. 错误恢复关闭5. Error recovery cooldown

对于常规模式中的一些响应,恢复冷持续时间(以秒计)可能通过标头 Retry-After 提供。For some of the responses in the regular pattern, a recovery cooldown duration in seconds might be provided via a Retry-After header. 当存在恢复冷淡持续时间时,Microsoft Graph 客户端不会在指定的持续时间过去之前发送任何后续请求。When a recovery cooldown duration is present, the Microsoft Graph client is not expected to send any followup requests before the specified duration passes.

特殊情况处理Special case handling

对于会话请求,如果遇到错误或错误,当二级错误代码在详细错误代码中列出时,请分析二级代码并按照相应的说明操作;否则,我们将重新确认您直接重新创建会话。 502/badGateway 503/serviceUnavailable For sessionful requests, if you encounter a 502/badGateway or 503/serviceUnavailable error, when a second-level error code is listed in Detailed error codes, parse the second-level code and follow the corresponding instructions; otherwise, we reconmmend that you recreate the session directly.