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.

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

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.

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.

Related content

• Use the Excel REST API