Rate Limiting

How the API’s rate limiting works.

📘

Rate Limiting Enabled 2/6/2025

On February 6th, 2025 the rate limiting protection will be enabled as described in this article. As of January 10th, 2025 the API is returning the HTTP headers mentioned in this article to aid developers in adapting their solutions to abide by the rate limits.

Overview

We have introduced rate limiting to ensure consistent performance and reliability for all users of our PBX API. Our rate-limiting implementation uses two key HTTP response headers:

1. RateLimit-Policy
2. RateLimit

These headers provide clients with the policy information and current usage status, enabling them to proactively throttle requests and avoid hitting hard rate-limit errors.

Example Clients

An example client that respects the PBX API rate limits by parsing the response rate limit headers has been published here.

Default Limits

The PBX API enforces four policies by default:

1. subscriber_minute
   1. 60 requests per minute
2. subscriber_hour
   1. 1800 requests per hour
3. client_minute
   1. 90 requests per minute
4. client_hour
   1. 2700 requests per hour

If your application exceeds any of these limits, the PBX API will return an HTTP 429 (Too Many Requests) error response, indicating you have been throttled. Additional requests should wait until the rate-limit window resets.

Example Response

Below is a sample API response (simplified). The headers of interest are RateLimit-Policy and RateLimit.

http

HTTP/1.1 200 OK  
RateLimit-Policy: "subscriber_minute";q=60;w=60;pk=:MTExODNAc2t5c3dpdGNoLjE1NjExLnNlcnZpY2U=:,  
                  "subscriber_hour";q=1800;w=3600;pk=:MTExODNAc2t5c3dpdGNoLjE1NjExLnNlcnZpY2U=:,  
                  "client_minute";q=90;w=60;pk=:bnMtZGV2:,  
                  "client_hour";q=2700;w=3600;pk=:bnMtZGV2:  
RateLimit: "subscriber_minute";r=59;t=31;pk=:MTExODNAc2t5c3dpdGNoLjE1NjExLnNlcnZpY2U=:,  
           "subscriber_hour";r=1799;t=331;pk=:MTExODNAc2t5c3dpdGNoLjE1NjExLnNlcnZpY2U=:,  
           "client_minute";r=89;t=31;pk=:bnMtZGV2:,  
           "client_hour";r=2699;t=331;pk=:bnMtZGV2:  
Vary: Accept-Encoding  
Content-Encoding: gzip  
Content-Length: 227  
Keep-Alive: timeout=5, max=100  
Connection: Keep-Alive  
Content-Type: application/json; charset=UTF-8

[{"domain":"abc.111.service","description":"ABC Domain", ... }]

Breaking Down the Headers

1. RateLimit-Policy
   Lists the policies associated with your subscriber or OAuth client.
   Each item is structured like "policy_id";q=XXX;w=YYY;pk=<base64>:
policy_id: A label for this rate-limit policy (e.g., "subscriber_minute", "client_hour").
   q: The quota (total allowed requests) for that policy within its time window.
   w: The window duration (in seconds). For example, w=60 means 60 seconds (1 minute).
   pk: The partition key representing the specific subscriber or client. It’s base64‑encoded per the RateLimit draft specification.
2. RateLimit
   Displays current usage information for the same policy IDs.
   Each item is structured like "policy_id";r=RRR;t=TTT;pk=<base64>:
r(Remaining): How many requests remain in the current window.
   t(Time): How many seconds until the current window resets.
   pk: Again, the partition key to identify which entity (subscriber or client) the numbers are for.

Example Interpretation

In the line:

"subscriber_minute";r=59;t=31;pk=:MTExODNAc2t5c3dpdGNoLjE1NjExLnNlcnZpY2U=:

• subscriber_minute policy has 59 requests remaining (r=59)
• The 1-minute window resets in 31 seconds (t=31)
• pk=:MTExODNAc2t5c3dpdGNoLjE1NjExLnNlcnZpY2U=: corresponds to a unique, Base64-encoded partition key (essentially your subscriber or client identifier).

Programmatically Handling Rate Limits

1. Read the Headers
   When your application receives an HTTP response, parse the RateLimit header to see how many requests remain (r) and how long until the window resets (t). This tells you when it’s safe to issue additional requests without exceeding the limit.
2. Throttle Accordingly
   If you see you are nearing 0 remaining requests, you can:
   1. Slow down your request rate, or
   2. Temporarily pause until the reset time (t seconds have passed).
3. Watch for 429 Responses
   If your application exceeds the limit, you will receive a 429 (Too Many Requests) status code. This indicates you are temporarily throttled and should back off until the reset time has elapsed which is communicated by the RateLimit header.

Further Details

For an in-depth look at how rate-limit headers are structured, please refer to the RateLimit Headers draft specification.