Debug and handle errors with the OneNote API

  • Article

Use the information in this topic to troubleshoot errors returned by the Microsoft OneNote API.

Applies to: OneNote service

In this article
HTTP error codes
Causes for common errors
Helpful debugging tools
X-CorrelationId header

This topic lists the HTTP status codes that the OneNote API returns. To help you debug your app, we've also listed common causes for API-related errors you might see in your apps. We've included links to some useful tools that have helped us debug our own apps, and provided information about the X-CorrelationId header returned by the API.

HTTP error codes

The Microsoft OneNote API is REST-based, and so is built on top of HTTP. The API doesn't return all the possible HTTP error codes listed in RFC 2616 standard or in this excellent list on Wikipedia. Instead, the OneNote API returns the status codes in the following table. Some errors return more explanation in the response body, but not all of them do. If you're having trouble getting your app to work, check the next section for ideas about what might be causing the errors.

HTTP Status Code

201 - Created The POST request succeeded in creating the new page. This is the default success result from the pages POST request. Some processes, like OCR, can take a few moments to process, so your app might receive the 201 status before the data becomes available in OneNote.

400 - Bad Request A syntax or other error was detected in a request your app sent.

401 - Unauthorized Problems occurred in authenticating the token, user or your app.

413 - Request Entity Too Large The request was larger than the API can process.

415 - Unsupported Media Type The request entity has a media type which the server or resource does not support.

500 - Internal Server Error A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Causes for common errors

Below are some possible causes for errors returned by the OneNote API:

-
400 - Bad request

  -  
    **MIME formatting** The format of MIME multi-part data has problems, like missing blank lines, missing last line, incorrectly formatted part separators, and so on. If you're building the multi-part message by hand, carefully check the logic, or consider using a third-party library.

  -  
    **Json serialization in the API** Sometimes when a page title uses international characters, even when the OneNote page is created correctly, the API can have trouble formulating the Json block of links it sends back to the app.

  -  
    **Content-type issues** The Content-type header for the overall request must be multipart/form-data or text/html. Verify that each part has its own content-type line, and that it matches the data your app sends. Web-based applications sometimes use Content-type=application/x-www-form-urlencoded, but the OneNote API only supports multipart/form-data.

  -  
    **Presentation part issues**. If your app sends multi-part messages, one and only one part must be named "Presentation". Verify that it exists, and the name is spelled correctly.

  -  
    **Part or request sizing issues** The OneNote API limits the amount of data in any one part to 25 MB maximum, and the request must be smaller than 70 MB total.

  • 401 - Unauthorized

    • Credentials and token issues This type of error can be very difficult to troubleshoot because it can occur because of a wide variety of reasons, sometimes related to putting an incorrect client ID (or package ID for Windows store apps) in your app source code. These errors can occur when very unusual things happen, like a user's Microsoft account has been deactivated but they just authorized your app. Check the Error object in the Windows Live Connect SDK developer guide.

  • 413 - Request entity too large

    • Part or request sizing issues The OneNote API limits the amount of data in a request to 70 MB maximum.

  • 415 - Unsupported media type

    • Content-Type is not compatible with the OneNote API. Verify that the content type is compatible with the API, and is not misspelled.

  • 500 - Internal server error

    • Have your app tell the user to try again later. They can be due to Microsoft OneDrive issues like the user's account being over their storage limit or even OneDrive being down.

Helpful debugging tools

The developer world has many platform-specific debugging tools, often included with the IDE or SDKs, in the device emulators, and so on. The following are a few that we've found helpful:

  • Network monitoring tools can sometimes help resolve issues by showing exactly what's going over the wire between your app and the OneNote API. We've used Fiddler on Windows, and they have an early Mono-based Mac version. WireShark is also a popular tool.

  • Device emulators provide an environment where you can try your code on devices you don't own, and without having to load it onto the physical device. When developing Android, iOS and Windows Phone apps that use the API, you should be able to access the API without problems from device emulators.

    Opening the native OneNote clients from a Windows Phone or Android phone emulator can have problems, however. If you're trying to use the oneNoteClientURL links in either the Windows Phone or Android phone emulators, be sure to read the topic Open the OneNote clients with the OneNote API.

For more information, see Get tools and libraries to use with the OneNote API.

X-CorrelationId header

In addition to the standard HTTP response codes, the OneNote API returns headers to the calling app. Included with every response is an X-CorrelationId header, with a GUID value, that looks like this.

X-CorrelationId : d2d6aaf5-3bde-4ee7-ba18-27727bf3cffe

The CorrelationId header ties together the various pieces in the backend servers. Your app can log this GUID value when you need to work with Microsoft support to resolve problems in your app or the API. The values are not sequential, which means you can't use them to establish an order of page creation.