Throttling
To keep our API healthy and protect it from overuse, we set limits on the number of calls you can make per time interval. When developing your app, make sure to respect the API call limits.
Types of Limits
Our API has the following limits in place:
- Application limit is set per one client application — or more accurately described, per
client_id
. - Company limit is determined globally for the entire company. Company here is either a subscriber or a provider, so this limit is per
SubscriberId
orProviderId
.
Default Call Limits
These are our default throttling limit values for the Production environment:
- Application limit: 300 requests/minute
- Company limit: 600 requests/minute
These are our default throttling limit values for the Sandbox2 environment:
- Application limit: 40 requests/minute
- Company limit: 80 requests/minute
Important: The default limits are subject to change at any time, without notice.
Access Token Request Limit
For security reasons, you can send a POST request to https://login.servicechannel.com/oauth/token
only once in 5 seconds. The limit is set per user.
In case you exceed this limit, you will receive 429
status code and the following header:
Error-Message: Rejected by security reason: Login attempts limit exceed.
Remember that access_token
that you receive in the response to this authentication request expires in 600 seconds, so store the token value, and use it until you need to refresh your access token.
Reaching Limits
When the limits are exceeded on the Production environment, our API returns the following response body:
{
"Reason": "Request has been throttled. Your current Application limit is [300] per [1] minute"
}
When the limits are exceeded on the Sandbox2 environment, our API returns the following response body:
{
"Reason": "Request has been throttled. Your current Application limit is [40] per [1] minute"
}
The response body contains information on the number of calls you can make per time interval as well as the type of limit you have reached. The Retry-After
header states the exact time when you can resend your request.
Retry-After Header
The Retry-After
HTTP header is used by servers to indicate how long you should wait to try again. It is traditionally added to the 429
status code and is specified in the HTTP-date format — denoting the exact date and time when the throttling window ends.
HTTP/1.1 429 Request has been throttled. Your current application limit is [3] per [1] minute
Retry-After: Wed, 09 Jul 2025 06:37:17 GMT
Throttling Types
The behavior of the Retry-After
header can vary depending on the type of throttling being applied. Note that the two types are working in sync.
- TYPE 1: Based on the number of requests per minute. The
Retry-After
header is returned together with the429
status code. - TYPE 2: Based on the execution time of previous requests. It doesn’t impose penalties, meaning that the request doesn’t get rejected or blocked.
The
Retry-After
value is dynamically calculated based on how long the previous request took to execute. It is returned with the expected status code and serves as a recommendation to prevent system overload.
Criterion | Traditional Throttling | Execution-Time-Based Throttling |
---|---|---|
Based on | Request count | Request duration/load |
Penalties | Yes (e.g., 429 code) | No |
Calculating the Total Throttling Factor
The total throttling factor is a sum of the throttling factors related to the system slowness (see TABLE 1) and to the slowness of the public requests (see TABLE 2). See how throttling is calculated depending on the request execution time and the IsGlobal
flag.
TABLE 1: Current throttling factors related to the system slowness.
- IsGlobal: The throttling rule is applied globally across the entire system
IsGlobal=1
. - Average Execution Time (seconds): The average execution time for all requests over the specific period of time.
- Throttling Factor (seconds): The amount of time (in seconds) that must pass between requests.
For example, if the average execution time of all requests doesn’t exceed 15 seconds, then no throttling penalty will be applied.
IsGlobal | Average Execution Time (seconds) | Throttling Factor (seconds) |
---|---|---|
1 | 15 | 0 |
1 | 30 | 2 |
1 | 60 | 4 |
1 | 120 | 8 |
1 | 240 | 16 |
1 | 500 | 32 |
1 | 1000 | 64 |
1 | 2419200 | 128 |
TABLE 2: Throttling factors related to the slowness of the public requests (application integration).
- IsGlobal: The throttling rule is applied to the application integration
IsGlobal=0
. - Execution Time (seconds): The amount of time (in seconds) that each request takes to process.
- Throttling Factor (seconds): The amount of time (in seconds) that must pass between requests.
IsGlobal | Execution Time (seconds) | Throttling Factor (seconds) |
---|---|---|
0 | 2 | 0 |
0 | 6 | 1 |
0 | 10 | 2 |
0 | 30 | 4 |
0 | 60 | 8 |
0 | 180 | 16 |
0 | 360 | 64 |
0 | 2419200 | 128 |
Let’s calculate the total throttling factor for a request that runs for 18 seconds.
- 2 seconds penalty from system slowness (range between 15 and 30 seconds of Execution Time)
- 4 seconds penalty per application integration (range between 10 and 30 seconds of Execution Time)
The total penalty will be 2 + 4 = 6 seconds for the request
Retry-After = Time.Now + 6 seconds
.