Error Handling

Evernote Cloud API error types and their common causes

---

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.

Common error cases

When using the Cloud API, you should ensure that you correctly handle the following error conditions:

Authentication failed

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.

Quota exceeded

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_REACHED.

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.

You can determine the user's service level, total monthly upload quota, remaining quota, and quota rollover 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 this case, an EDAMUserException will be thrown with the error code LIMIT_REACHED and a parameter value of Note.size.

The note size limit differs according to a user's service level. The specific limits can be retrieved in a User's accountLimits.noteSizeMax.

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.

Other note limits

The EDAMUserException with the error code LIMIT_REACHED can also indicate other note limits being reached:

Parameter	Limit
Note	Maximum number of notes per account.
Note.size	Total note size too large.
Note.resources	Too many resources on note.
Note.tagGuids	Too many tags on note.
Resource.data.size	Resource too large.