Evernote Cloud API error types and their common causes
As with any API, your application will need to handle errors that can occur when you use the Cloud API. This page discusses the general error reporting strategy used by the Cloud API and covers some of the most common types of errors.
Categories of errors
The Cloud API returns three specific categories of errors. The Cloud API wrapper libraries report these errors by throwing exceptions. The reference documentation for each API call lists the exact reasons that exceptions can be thrown.
EDAMUserException is thrown when the error was caused by incorrect input from the caller of the API. Such exceptions can be resolved by the calling application. For example, an EDAMUserException is thrown when an API call is made with an expired authentication token. To determine the exact cause of the error, see the errorCode and parameter fields of the exception.
EDAMSystemException is thrown when the error was caused by an internal Evernote web service error. Such exceptions cannot be resolved by the calling application. To determine the exact cause of the error, see the errorCode and parameter fields of the exception.
EDAMNotFoundException is thrown when an API call refers to an object that does not exist. For example, an EDAMNotFoundException is thrown when NoteStore.getNote is called with a GUID for a note that doesn't exist in the user's account.
Your application should never automatically retry a failed Cloud API call when an EDAMUserException or EDAMNotFoundException is thrown. These errors will not resolve themselves.
EDAMSystemExceptions may resolve themselves if you retry your API call, but you should wait a suitable amount of time between attempts (e.g. 15 minutes).
Common error cases
When using the Cloud API, you should ensure that you correctly handle the following error conditions:
When making NoteStore calls, authentication fails for several reasons. In this case, an EDAMUserException will be thrown with an error code and parameter that indicates the reason for the failure. You should check for and handle the following error codes:
- AUTH_EXPIRED - The authentication token has expired. You will need to reauthenticate and obtain a new authentication token before making further NoteStore calls.
- PERMISSION_DENIED - The authentication token doesn't contain have sufficient permissions for the API call being made. Your application will not be able to perform the requested operation unless you contact our developer support team to extend your API key's permissions.
The Evernote web service limits the amount of data that each user can upload to their account every month. Calls to NoteStore.createNote and NoteStore.updateNote can fail if the user does not have sufficient quota remaining to perform the requested operation. In this case, an EDAMUserException will be thrown with the error code QUOTA_EXCEEDED.
When your application hits the user's quota, it should inform the user that they have reached their monthly quota and cannot create or update the requested note. Users with a Free Evernote account can obtain additional quota by upgrading to Evernote Premium. Users with a Premium account can obtain additional quota by purchasing one-time quota increases. These actions are performed in the Evernote web application and cannot be initiated by your application.
You can determine the user's service level (free or Premium), total monthly upload quota, remaining quota, and quota rollever date through the Cloud API:
Maximum note size
The Evernote web service limits the maximum size of an individual note. Calls to NoteStore.createNote and NoteStore.updateNote can fail if the new size of the note would be larger than the maximum allowed. In thise case, and EDAMUserException will be thrown with the error code LIMIT_REACHED.
The note size limit differs for free and Premium users. The limits are currently 25MB for free users and 100MB for Premium users, but your application should not hardcode these values, since we might change them. Instead, you should use the constant values EDAM_NOTE_SIZE_MAX_FREE and EDAM_NOTE_SIZE_MAX_PREMIUM from the Cloud API wrapper libraries.
Your application should check that notes don't exceed the size limit before creating or updating a note. The size of a note is calculated as the number of unicode characters in the note content plus the sum of all attached resources in bytes. In practice, it's normally sufficient to check that the sum of the sizes of the attached resources doesn't exceed the maxiumium.