OneNote API calls fail with a large number of items in a SharePoint document library

Hello world! Paresh Moradiya and Sri Srinivasan, members of the OneNote API team here. We've heard from some of you saying that you're running into issues when accessing SharePoint-hosted notebooks in very large document libraries. We have come up with some instructions on how you can eliminate these OneNote API failures.

The problem

Applications call the OneNote REST API to create or access OneNote content in Office 365. Sometimes the OneNote API calls can fail when they are executed against SharePoint document libraries that contain a large number of items (items can be folders or files, some of which could be OneNote entities such as notebooks, sections or section groups).

When working with SharePoint document libraries that contain a large number of items, the OneNote API service is subject to throttling measures implemented by SharePoint for the purposes of regulating resource usage. Under these circumstances, the user of the application may see an application-specific error. The application calling the OneNote API will itself receive one of the errors below:

{
"error": {
"code": "10008",
"message": "One or more of the document libraries on the user or group's OneDrive contains more than 5,000 OneNote items (notebooks, sections, section groups) and cannot be queried using the API. Please make sure that none of the user or group's document libraries contains more than 5,000 OneNote items. Please follow the link below for instructions on how to remedy this situation.",
"@api.url": "http://aka.ms/onenote-errors#C10008"
}

{
"error": {
"code": "10013",
"message": "One or more of the document libraries on the user or group's OneDrive contains more than 20,000 items and cannot be indexed for querying using the API. Please follow the link below for instructions on how to remedy this situation.",
"@api.url": "http://aka.ms/onenote-errors#C10013"
}

The solution

To mitigate the OneNote API failures described above, you must first assess the current state of the SharePoint document libraries on the SharePoint site and then take a few remedial steps based on the current state.

Assess the current state

Download the OneNote API Diagnostics tool available here and follow the steps below.

  1. Enter the following parameters into the tool
    Parameter Description
    SharePoint URL The SharePoint site's URL. For example, a user's personal site might use the format https://<<Your Tenant>>-my.SharePoint.com/personal/<<Your email address - Replace all "." with "_">> (contact your administrator for the format of your personal site's URL) You can also enter the URL for a non-personal SharePoint site
    User Your Office 365 user name (email address)
    Password Your office 365 password
  2. Click the "Get Info" button. This will fetch the diagnostic information from the specified SharePoint site. The operation may take a few seconds to process.

NOTE: The tool processes only the default document library on the SharePoint site by default (for a user's personal site, this is the user's OneDrive for Business). If the API issues above are not resolved by just targeting the default document library, you can choose the tool's option to target all document libraries on the SharePoint site.

Take appropriate remedial steps

Based on the output of the diagnostics tool, you can take the remedial steps suggested below. These steps are applicable at a document library level. If you chose to target all document libraries on the SharePoint site, you will need to execute the remedial steps below on all the document libraries.

Case 1: Items Count is greater than 20,000

If Items Count is greater than 20,000 and File Type = false or HTML File Type = false, then you need to bring the item count in the document library to under 20,000. You can do this by moving items out of the document library to a different storage location (such as another user or group's OneDrive). You can also delete the items that are not required anymore.

After you have reduced the item count to under 20,000, rerun the tool to make sure the items count is less than 20,000. Click the "Build Index" button so the required indexes are built for the OneNote API to work properly.

Case 2: Sections Count is greater than 5,000

If Sections Count is greater than 5,000, then you need to bring the section count in the document library to under 5,000. You can do this by moving some of your notebooks out of the document library to a different storage location (such as another user or group's OneDrive). You can also delete the notebooks that are not required anymore.

After you have reduced the section count to under 5,000, rerun the tool to make sure the sections count is less than 5,000. Ideally you should keep this number below 5,000 so that you can have enough room to create new sections. If the sections count in the document library crosses 5,000 again, you will start seeing the OneNote API failures and you will need to come back here and take the same remedial steps.

Case 3: Folders Count is greater 5,000

If Folders Count is greater than 5,000, then you need to bring the folder count in the document library to under 5,000. You can do this by reorganizing the content in the document library and eliminating folders. You can also delete the folders that are not required anymore.

After you have reduced the folder count to under 5,000, rerun the tool to make sure the folder count is less than 5,000. Ideally you should keep this number below 5,000 so that you can have enough room to create new folders. If the folder count in the document library crosses 5,000 again, you will start seeing the OneNote API failures and you will need to come back here and take the same remedial steps.

Case 4: Notebooks Count is greater than 5,000

If Notebooks Count is greater than 5,000, then you need to bring the notebook count in the document library to under 5,000. You can do this by moving some of your notebooks out of the document library to a different storage location (such as another user or group's OneDrive). You can also delete the notebooks that are not required anymore.

After you have reduced the notebook count to under 5,000, rerun the tool to make sure the notebook count is less than 5,000. Ideally you should keep this number below 5,000 so that you can have enough room to create new notebooks. If the notebook count in the document library crosses 5,000 again, you will start seeing the OneNote API failures and you will need to come back here and take the same remedial steps.