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
In sandbox and production alike, 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.
Sandbox v. Production
The only difference is that if an application connecting to Sandbox exceeds the allowed number of requests, the calling application will only need to wait a maximum of 15 seconds before retrying the rejected request. They will receive the same exception as production applications and the
rateLimitDuration attribute associated with the
EDAMSystemException instance will be set appropriately. This way, developers can test and handle the rate limit exception without having to wait until the one-hour interval ends to resume interacting with the API.
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
EDAMUserExceptionfrom 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.getSyncStateperiodically 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.getNoteand the entire note (including associated
Resources), try setting the optional
withResourcesDataflag when calling
NoteStore.getNoteso that all
Resourcedata is included in the response rather than individually calling
Resourcecontained in the note (which would mean one API request per
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.