People Make Mistakes - API Errors Now Help You Fix Them

  • Article

Hey OneNote API Developers,

I'm Nick, the most recent addition to the OneNote API team. My charge is creating a world class user experience for you, our developers. If you've any questions about the OneNote API – or just want to talk about PLs – you can find me on Twitter and GitHub as @nickbarnwell.

A core part of our commitment to building a world class developer experience is improving the feedback developers receive when something goes wrong with an API request. In their phenomenal post on best practices for errors Box handily demonstrates how important descriptive, actionable errors are to a developer-friendly API experience.

Today we're debuting a completely new set of errors and warnings on our beta API endpoint. We hope these changes will simplify the process of creating and debugging applications built on top of the OneNote API.

As always, we welcome your feedback on Twitter and UserVoice – if you think there are any improvements we could make, do let us know!

Now, onto the nitty gritty:

New Error Format

When a request encounters an error a JSON object containing details about the error is returned:

 {"error": {

  "code":"20001",

  "message":"The request is missing the required 'Presentation' part. 

  Exactly one is required. See OneNote POST pages for more information.", 

  "@api.url": "https://go.microsoft.com/fwlink/?LinkID=400805"

 }}

The error field of will always contain an object with the following properties:

  • code: The OneNote Service-specific error code
  • message: A human-friendly message containing details of yout
  • @api.url: A link to MSDN containing more information about the error and possible resolutions. These links will not resolve until the feature is released into production.

An appropriate HTTP 4xx status code is always returned along with the error.

Warnings

Warnings provide information about partially unacceptable data or non-fatal errors encountered while processing a request.

A single request may contain more than one warning. Accordingly, warnings are always returned as an array of JSON objects.

 {

  "api.diagnostics@odata.type":"#Collection(Microsoft.OneNote.Api.Diagnostic)",

 "@api.diagnostics": [

  { "message": "Created date/time string 5/5/2014 in 'Presentation' part html did not match any of the allowed formats", 

  "url" :"https://go.microsoft.com/fwlink/?LinkID=400816" }

  ],

  ...(rest of response)

 }

The array of warnings is always found under the @api.diagnostics key. Because warnings are intended for debugging (as opposed to machine response) they lack a program-addressable code attribute.

What's this Beta Endpoint?

As Jorge described in the Beta Announcement, the beta endpoint is where we'll deploy not-quite-complete features for about a month to collect feedback and determine whether there are any changes needed before they're officially released on versioned endpoints.

The tl;dr for using the beta endpoint:

When executing any type of operation against our API, you specify a version:

POST https://www.onenote.com/api/v1.0/pages

By specifying a beta version, you'll have access to our freshest, newest set of features we offer:

POST https://www.onenote.com/api/beta/pages

For the gory details, go check out the beta endpoint announcement!

We are excited to see how you're going to respond to these improved errors and warnings and look forward to hearing how you like them in our blog's comments and on Twitter at @onenotedev.

—Nick