Rate Limits

A usage guideline for third-party developers

In an effort to ensure the best possible performance of the Evernote service, we have implemented rate limits for third-party applications and services. This document is an overview of the rate limits themselves, as well as how they are enforced and best practices for handling the errors returned when a rate limit is reached.

Rate Limits Overview

Third-party applications are identified using their API key. End user requests are further identified by their authentication credentials. Rate limits are applied to calls against the Evernote API on a per API key, per user, per time period basis. This means that the API limits the number of calls a third-party app can make for each individual user during a given one-hour period.

For example: imagine that Bob uses the non-existent Fake App—which integrates with Evernote—and Fake App makes a series of requests of the Evernote API to Bob's account. If these API requests exceed the rate limit set by Evernote for a one-hour period, any subsequent API requests in the time window will result in an exception thrown by the Evernote API (more on that in a minute).

This does not mean that Bob will not be able to access his Evernote data — only that Fake App will be disallowed from making requests for the balance of the hour until the limit is reset. All other applications and services Bob uses to access his Evernote data will still have access (unless they also reach the limit, of course).

Rationale for Rate Limits

As previously mentioned, our primary goal is to provide a responsive interface for developers and users to use when accessing the data in their Evernote accounts. Since each request made to the API incurs a computational cost, it’s in the best interest of both Evernote and its developer partners that these costs be minimized to the greatest degree possible.

Rate limiting also helps third-party developers by encouraging them to build their integrations to make economical use of API requests.

Rate Limit Enforcement & Handling

Rate limits apply to all authenticated API calls — those that take an authenticationToken parameter. If a request is made after the rate limit is reached, an EDAMSystemException is thrown with the RATE_LIMIT_REACHED error code. In addition, the rateLimitDuration attribute is set on the EDAMSystemException instance. This value represents, in seconds, the time that must elapse before another API request will be allowed for that combination of user and API key.

Elegant handling of this condition is important. The fact is that the user, in most cases, won’t be familiar with the concept of rate limits and will likely not understand why their request failed. If the offending request was meant to change something in the user’s account (NoteStore.createNote, for example), it is preferable that integrated applications queue such requests until the number of seconds indicated by rateLimitDuration have passed and the request can be resent.

Rate limits effective dates

Rate limits will be applied to all new API keys beginning August 14, 2013. For existing API keys that have already been activated on production, rate limits will take effect on November 18, 2013.

Common Reasons for Exceeding Rate Limits

There are a few ways in which developers can unnecessarily exceed the rate limit for their API key:

Repeatedly retrying failed API calls — It’s particularly important that integrations with Evernote pay close attention to error codes returned with exceptions and individually handle the different exception types. Specifically, if your application receives an EDAMUserException from the API, this means that the problem is with the application’s request, not an error in the API itself.
Polling for changes — While calling NoteStore.getSyncState periodically is one possible way to be notified if the current user’s account has changed, third-party developers performing this type of polling might consider instead using web hooks to be notified when the notes in a user’s account have changed.
Inefficient algorithms — Ensure that your application is making the most of each API request. For example, if you retrieve a single note using NoteStore.getNote and the entire note (including associated Resources), try setting the optional withResourcesData flag when calling NoteStore.getNote so that all Resource data is included in the response rather than individually calling NoteStore.getResource for each Resource contained in the note (which would mean one API request per Resource).

Initial Sync Boost

Third-party applications that synchronize all (or most) of a user's data may exceed the rate limit during their initial synchronization (because they have to fetch so much data at once). We have implemented a mechanism called "Initial Sync Boost" temporarily increases the rate limit significantly to avoid such a situation. The increase will be effective for 24 hours after an authentication token is issued. Once the period expires, the rate limit will return to normal.

The Initial Sync Boost is intended for applications that synchronize user data and is not enabled on new API keys by default. You may request this when your key is created or when you are activating your API key in our production environment. This functionality is not available with developer tokens.

Got questions? Get in touch

If you have any questions about how rate limiting works or if you’d like to discuss a special case for your integration, feel free to contact Evernote developer support.