API Key Rate limits

Guideline for Customers, Partners and third-party developers

To ensure the best possible performance of Lumesse TalentLink Web services, we have implemented rate limits and quotas for pre-packaged API bundles and services.

This document is an overview of the rate limits themselves, as well as how they are enforced and contains best practices for handling the errors returned when a rate limit is reached.

Rates and quotas have been established and mentioned in terms of developer classes for your account in the account setup phase. For more information, please see your activation documentation.

API Call limits

The limits on the total calls and the rate at which the calls can be made depend on the service and per API Key.

Please note that rate limits are not per endpoint, but for a bundle. For example: if a customer opts for the "Low" access package of USER bundle (used to synchronise foundation data like Users, OBS, Roles); this would allow users to make a maximum of 12,000 calls per month. Making a series of requests to only create/Synchronise users could potentially exceed the rate limit set, thus not allowing any further requests to be made to other endpoints that are part of the same bundle, like OBS or Roles; any subsequent requests in the time window will result in an exception thrown by the TalentLink Web Services.

Definitions

  • Quota limits: Quotas define the call limits allowed in a time period. This quota is reset daily enforced over a rolling 30 days.
  • Throttling   : Throttling defines the call frequency allowed. Currently this is calls per second or queries per second (QPS).

Bundle Developer Class
Low (Default)

Medium

Unlimited
User Admin 12,000 calls/month
2 calls/second
36,000 calls/month
2 calls/second
Unlimited calls/month
5 calls/second
Career portal 28,000 calls/month
5 calls/second
84,000 calls/month
5 calls/second
Unlimited calls/month
5 calls/second
Posting 2,500 calls/month
5 calls/second
7,500 calls/month
5 calls/second
Unlimited calls/month
5 calls/second
Assessment 8,000 calls/month
2 calls/second
24,000 calls/month
2 calls/second
Unlimited calls/month
5 calls/second
Background Check 7,000 calls/month
5 calls/second
21,000 calls/month
5 calls/second
Unlimited calls/month
5 calls/second
HRIS 12,000 calls/month
2 calls/second
36,000 calls/month
2 calls/second
Unlimited calls/month
5 calls/second
Timesheets 20,000 calls/month
2 calls/second
40,000 calls/month
2 calls/second
Unlimited calls/month
5 calls/second

Rate Limit Handling

Rate limits apply to all authenticated TalentLink Build Web service calls. If a request is made after the rate limit is reached, an HTTP error is thrown, which is to be handled elegantly. We recommend that interface applications queue such requests until the number of seconds indicated by rate limit/frequency duration have passed and the request can be re-sent.

If either the rate limit or rate frequency is exceeded,the following errors will be thrown, and must be handled.
******* Error Message for Limits, applies to Monthly Limits*******
HTTP/1.1 403 Forbidden
X-Mashery-Error-Code: ERR_403_DEVELOPER_OVER_RATE
Exception: Developer Over Rate


******* Error Message for Throttle limit, applies to number of calls per second*******
HTTP/1.1 403 Forbidden
X-Mashery-Error-Code: ERR_403_DEVELOPER_OVER_QPS
Exception: Developer Over Qps

If you do exceed your limit please contact your Lumesse Account Manager or alternatively feel free to contact Lumesse support, to help you get back on track.

Best Practice tips to avoid being Rate Limited

The following will help you code defensively and reduce the possibility of being rate limited. Certain application features that you may want to provide are simply not possible in light of rate limiting, in particular when you require time-sensitive results. If real-time information is an aim of your application, please consider requesting Unlimited developer class access.

Caching

Store API responses in your application or on your site if you expect a lot of use. For example, don't try to call the FOAdvert Web service, method "getCriteria" on every page load of your website landing page. Instead, call the API infrequently (once a Day) and load the response into a local cache. When users hit your website load the cached version of the results.

Scheduling

Please refrain from having your interfaces start up at a certain time of the day to perform certain actions. For instance, having your application start at 07:00 local time and query/sync a lot of data at the same time that TalentLink application users start the day is a bad idea. If you program your interface this way then there could be a direct impact on the general performance of the web services. If there is a task you would like to perform in the background during peak times you should have your interface application make calls at random intervals throughout the day. If the application spreads its calls throughout the day, it spreads the load on the server across the day as well, which avoids creating artificial peak times.

Avoid sending requests too fast, i.e. too many requests per second, when there is no need to do so. For example: assessment providers do not need to poll for orders every second, but can instead schedule checks once every 15 minutes.

If you would like us to review your scheduling plans, do feel free to contact your Lumesse Account Manager or alternatively contact Lumesse support.

Monitoring usage

If you are expecting a considerably high volume of usage and are unsure of the numbers then consider opting for "Medium" access for the initial months and monitor usage over 3 months. This will enable you to choose an appropriate access level based on actual usage.

Customers and developers can view all of their API Keys, including the usage reports for each, by logging into their developer portal account and clicking link "My Account"

Got questions?

If you require additional packages or if you’d like to discuss a special case for your integration, please contact your Lumesse Account Manager, or alternatively feel free to contact Lumesse support.