In this article I would like describe how throttling should be done in HTTP APIs designed to be used by third parties, which may be different from approach if the API is only used by internal clients (web or mobile). More specifically, considerations presented here are particularly relevant for applications which APIs are used by some sort of automation or integration app like workato.com. Again, if your API is designed to be used by interactive applications (your own or third-party) the tradeoffs and priorities are different.
HTTP 500 on general server overload.
HTTP 429 with
Retry-After header set upon API usage exceeding predefined quota.
API throttling is used to protect a system from overload by excess amount of otherwise legit requests or to impose a usage quota. When server decides to reject incoming request it responds with special error code and expects API client to stop sending requests and back off for some time. It does not protect you from harmful DoS / DDoS attackers, which don’t respect server response.
Possible throttling policies
When you decide to throttle incoming requests you can do it at different scope granularity. You can have single global limit per whole API across all users. Or you can account usage per particular user account. You can set different limits for authenticated users and guests, read and write operations etc. In any case do provide clear documentation on the policy you implement. Document limits and how user can change them, e.g. – use higher tier paid plan, or reach to support and have limits bumped up manually. Below are some popular policies. Here we consider all API operations being equal, you may want however to count significantly different operations separately. Good example here are Google and Amazon AWS cloud api which provide different quotas for read and write operation.
1. Application-wide limit
In this policy application as a whole (API provider) has a single limit of requests per second it can handle. It can be hard, like 1000 req/sec, or soft – start bouncing requests off as soon as server gets overloaded or both. In general it is a good practice to follow “fail fast” pattern and have a hard limit on API rate your servers are able to cope with rather than to try to execute each request with growing latency and see degraded service performance and stability. This method is easy to implement however throttling affect all users equally.
2. Limit per application (API key) or per traffic source (IP)
This imposes a limit on particular application which uses your API. This sounds as a natural thing to do if you give access to your API. However the problem with it is that end users can do nothing about it, and in most cases have no visibility of what is happening. User have application A and application B which are linked but not working because of some limits user have no idea of. If you impose this limit, set it high enough and provide a channel for application developers to request quota increase. Formally we can say that scope of the limit applied is
3. Limit per user on whose behalf API is being called
In this case limit is per user account (scope is
user_id). In this case many people can use integration between A and B without interference. The drawback is that if user has two integrations of application A with say B and C, then those application B and C will now interfere. And if throttling is requested B and C may not receive equal share of API “bandwidth”, as one application may start retrying more frequently than other and thus preempting it.
3a. Limit per authentication token(session), optionally limit number of tokens per account.
To resolve previous problem you may want to set a limit not per user account, but rather per authentication token, which will presumably be different for apps B and C. You can achieve similar result if you account per (user_id, api_key) tuple. This approach provides good isolation of particular application pairing for particular user. Careless approach would be to say it’s users’ responsibility to manage access among integrated apps, in reality users can do nothing about it.
I would recommend combination of all three quotas at different level. Let’s see example to see what I mean:
|Per API key (per integrated appication)||10,000 req/sec||We want to empower integrated apps, and let them do real work. We may change this limit based on support requests, partner agreements etc.|
|Per user account||100 req/sec||All integrated applications belonging to the same user can do 100 requests per second in total.|
|Per session||50 req/sec||Still we want to limit any single application from consuming all user’s quota.|
4. Subdomains or organizations (like workato.zendesk.com)
All logic of the above holds true, you want to limit amount of operations in particular scope. If you only support integrations at organization level (e.g. no individual org members can set up their own links), when you will probably have the following quote levels:
application_id(per API key)
organization_id(per organization as whole)
If additionally any org member has access to API and can do integration, then you additionally may have
(organization_id, user_id)(per user in organization)
(applicaiton_id, organization_id, user_id)(per user in organization using specific integration)
Rolling limit vs static intervals
There are two approaches to calculate api usage and detect when to activate the throttling. One is to have rolling window, say of 1000 requests per hour max. You count how many request you have had in last 60 minutes and if it is more than 1000 return appropriate error code. This is a bit tricky to implement, but delivers better recovery time. Easier approach is to start counting at the beginning of an hour, and reset it at the end. This is much easier to implement but then user needs to wait till the end of an hour even if overuse was negligible.
500 is ok if api global threshold is reached, as particular api user can do nothing about it other than retry with increasing back-off. In fact, in may be even easier for api consumers to have different error codes for different expected behavior.
Retry-After for managed back-off and
500 for generic back-off on global errors. This is example of how you should treat api limits in general – clearly indicate scope of the problem especially if expected handling is different. In practice you are unlikely to impose more complex combination than 1 plus any one of 2-4.
Let’s chat about clients a little bit. If client does not obey the throttling the discussed stuff does not make much sense. Client is behavior relatively simple — Back off for the time as specified by server if
retry-after is received (or functionally equal response as documented by api provider), or back off exponentially (or other algorithm with increasing retry interval) otherwise (500, or no retry-after header) as it should do with any retry-able error code.
Dropbox limits amount per
(application_id, user_id) unique tuple. It returns
503 for OAuth 1.0 requests and
429 for OAuth 2.0. See https://www.dropbox.com/developers-v1/core/docs and https://www.dropbox.com/developers-v1/core/bestpractices
Zendesk accounts per
organization_id and uses
429 response code with
Retry-After set. Refer tohttps://developer.zendesk.com/rest_api/docs/core/introduction#rate-limits
Google has multiple accounted usage scopes. It uses
403 HTTP result code with more detailed information about the scope inside JSON-encoded HTTP body. It has no indication when to retry and suggests to use exponential backoff. See https://developers.google.com/google-apps/calendar/v3/errors#403_daily_limit_exceeded