Error handling for Excel APIs
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
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
Retry-After: <Cooldown duration in seconds> (optional)
{
"error": <Error object>
}
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.
Note
Error responses follow the definition in the OData v4 specification for error responses.
{
"code": "string",
"message": "string",
"innerError": { "@odata.type": "odata.error" }
}
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 clients are expected to use the following steps to handle errors that occur with Excel APIs.
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. A long-running operation error will return a 200 OK HTTP status code and failed operation status in response body. A regular error response will return a corresponding HTTP error status code.
2. Parse second-level error code
For both the long-running operation pattern and the regular pattern, the client should first parse required second-level error codes and handle them according to the instructions. Optionally, the client can also handle other second-level error codes, or choose to fall back to top-level error codes or status codes.
The error codes are case insensitive.
Required second-level error codes
The following table lists instructions for required second-level error codes that Microsoft Graph clients are expected to handle. The service might add new error codes at any time.
| Code | Instructions |
|---|---|
accessConflict |
The failed request conflicts with other clients accessing the workbook (for example, another client has locked the workbook for edit). The Microsoft Graph client is not expected to resend the failed request until the conflict is resolved. An end user can choose to manually perform the same operations with Excel Online to get more details about the conflict. |
badRequestUncategorized |
An unspecified error is found in the failed request. The Microsoft Graph client is not expected to resend the failed request. |
conflictUncategorized |
The failed request conflicts with certain server state. The Microsoft Graph client is not expected to resend the failed request until the conflict is resolved. An end user can choose to manually perform the same operations with Excel Online to get more details about the conflict. |
forbiddenUncategorized |
The failed request is not allowed. The Microsoft Graph client is not expected to resend the failed request. An end user can choose to manually perform the same operations with Excel Online to get more details about the restrictions. |
gatewayTimeoutUncategorized |
The service wasn’t able to complete the request within the time limit. |
internalServerErrorUncategorized |
An unspecified error has occurred. 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. |
invalidSessionAccessConflict |
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. Recreating sessions with the same createSession request is not expected until the conflict is resolved. Recreating sessions with a different createSession request might or might not succeed. An end user can choose to manually perform the same operations with Excel Online to get more details about the conflict. |
invalidSessionAuthentication |
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. Recreating sessions with the same createSession request is not expected until appropriate authentication information is provided. |
invalidSessionNotFound |
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. Recreating sessions with the same createSession request is not expected. |
invalidSessionReCreatable |
The session specified in the request does not exist or is invalid due to a transient error. 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. |
invalidSessionRestricted |
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. Recreating sessions with the same createSession request is not expected until the restrictions or configurations blocking the request changes. Recreating sessions with a different createSession request might or might not succeed. An end user can choose to manually perform the same operations with Excel Online to get more details of the restrictions. |
invalidSessionUnexpected |
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. Recreating sessions with the same createSession request is not expected. Recreating sessions with a different createSession request might or might not succeed. |
invalidSessionUnsupportedWorkbook |
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. Recreating sessions with the same createSession request is not expected until the unsupported factors are removed. Recreating sessions with a different createSession request might or might not succeed. 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. |
methodNotAllowedUncategorized |
The HTTP method specified in the request is not allowed on the resource. The Microsoft Graph client is not expected to resend the failed request. |
notFoundUncategorized |
The requested resource cannot be found. The Microsoft Graph client is not expected to resend the failed request. |
notImplementedUncategorized |
The requested feature is not currently implemented. The Microsoft Graph client is not expected to resend the failed request. |
payloadTooLargeUncategorized |
The request payload exceeds the size limit. The Microsoft Graph client is not expected to resend the failed request. |
serviceUnavailableUncategorized |
The service is temporarily unavailable or is overloaded. The Microsoft Graph client is not expected to resend the failed request until the specified cooldown duration passes. |
tooManyRequestsUncategorized |
The failed request exceeds certain frequency limitation. The Microsoft Graph client is not expected to resend the failed request until the specified cooldown duration passes. For best practices to reduce throttling, see Reduce throttling errors. |
transientFailure |
The request failed due to a transient error. The Microsoft Graph client is not expected to resend the failed request until the specified cooldown duration passes. |
unauthorizedUncategorized |
Required authentication information for the resource is either missing or invalid. The Microsoft Graph client is not expected to resend the failed request. |
unsupportedWorkbook |
The request failed. The workbook contains unsupported features or exceeds the size limit. 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 that corresponds to the response. For the long-running operation pattern, the failed request is the one that triggers the failed operation.
Optional second-level error code examples
The following table lists examples of optional second-level error codes, including the corresponding handling instructions for each error code. The service might add new error codes at any time.
| Code | Instructions |
|---|---|
accessDenied |
You cannot perform the requested operation (for example, performing changes to locked cells). The Microsoft Graph client is not expected to resend the failed request. |
filteredRangeConflict |
The operation failed because it conflicts with a filtered range. The Microsoft Graph client is not expected to resend the failed request. |
generalException |
An internal error occurred while processing the request. The Microsoft Graph client is not expected to resend the failed request. |
insertDeleteConflict |
The insert or delete operation attempted resulted in a conflict. The Microsoft Graph client is not expected to resend the failed request. An end user can choose to manually perform the same operations with Excel Online to get more details about the conflict. |
invalidArgument |
The argument is invalid, missing or has an incorrect format. The Microsoft Graph client is not expected to resend the failed request. |
invalidReference |
This reference is not valid for the current operation. The Microsoft Graph client is not expected to resend the failed request. |
itemAlreadyExists |
The resource being created already exists. The Microsoft Graph client is not expected to resend the failed request. |
itemNotFound |
The requested resource doesn't exist. The Microsoft Graph client is not expected to resend the failed request. |
methodNotAllowed |
The HTTP method specified in the request is not allowed on the resource. The Microsoft Graph client is not expected to resend the failed request. |
nonBlankCellOffSheet |
Can't insert new cells because it would push non-empty cells off the end of the worksheet. The Microsoft Graph client is not expected to resend the failed request. An end user can delete rows or columns to make room for content to be inserted and then try again. |
rangeExceedsLimit |
The cell count in range has exceeded the maximum supported number. The Microsoft Graph client can try to send a request with smaller range size. For more information, see Resource limits and performance optimization for Office Add-ins. |
requestAborted |
The request was aborted during run time, which was usually caused by long time calculation from functions in the workbook. The Microsoft Graph client is not expected to resend the failed request. |
unsupportedOperation |
The operation being attempted is not supported. The Microsoft Graph client is not expected to resend the failed request. |
Note
For the regular pattern, the failed request is defined as the request that corresponds to the response. For the long-running operation pattern, the failed request is the one that triggers the failed operation.
3. Parse the top-level error code
If you can't find any known second-level error code, you should 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 and messages.
4. Parse the status code
For the regular pattern, if you couldn't find any known second-level error code or top-level error code, you should take action according to the HTTP status code.
5. Error recovery cooldown
For some of the responses in the regular pattern, a recovery cooldown duration in seconds might be provided via a Retry-After header. When a recovery cooldown duration is present, the Microsoft Graph client is not expected to send any follow-up requests before the specified duration passes. For best practices related to Retry-After header and throttling, see Reduce throttling errors.
Diagnostic information
All contents in the response that are not used in the previous steps are for diagnostics purpose only (including strings in the message fields). We don't recommend that you take a dependency on these contents as they might change without notice.
Special case handling
For sessionful requests, if you encounter a 502/badGateway or 503/serviceUnavailable error, when a known second-level error code is found, follow the corresponding instructions; otherwise, you should recreate the session directly.