API Rate Limits

← General

API Rate Limits

A rate limit is a policy that restricts how frequently an API endpoint can be called within a given time window. SIPSTACK applies rate limits to protect platform infrastructure from abuse and to maintain consistent performance for all users.

Rate Limit Policies

API requests are categorized into four policies, each with a different limit:

Policy	Rate Limit	Throttle Window
Light	50 requests/minute	60 seconds
Medium	40 requests/minute	60 seconds
Heavy	10 requests/minute	60 seconds
Auth	5 requests/minute	0 seconds

If you exceed the limit for a given policy, the server returns HTTP 429 Too Many Requests. The Retry-After response header specifies how many seconds to wait before retrying.

Rate Limit Response Headers

Every API response includes rate limit headers (unless the endpoint is unlimited):

Header	Description
X-Rate-Limit-Policy	The policy category for this request (Light, Medium, Heavy, Auth)
X-Rate-Limit-Limit	The maximum number of requests allowed in the current window
X-Rate-Limit-Remaining	Requests remaining in the current window
X-Rate-Limit-Window	The window duration in seconds

Example response headers:

HTTP/1.1 200 OK
X-Rate-Limit-Policy: light
X-Rate-Limit-Limit: 50
X-Rate-Limit-Remaining: 49
X-Rate-Limit-Window: 60
Content-Type: application/json; charset=UTF-8

Handling Rate Limits in Your Application

Single-threaded applications

1. Monitor X-Rate-Limit-Remaining in each response.
2. When it reaches 0, pause for the number of seconds specified in X-Rate-Limit-Window.
3. If you receive a 429 response, wait for the number of seconds in the Retry-After header before retrying.

Tip

If your application correctly monitors X-Rate-Limit-Remaining, it should never encounter a 429 error. Proactive backoff is more reliable than reactive retry.

Server overload (503 responses)

If the API returns HTTP 503 Service Unavailable:

1. Wait a default retry interval (e.g., 5–10 seconds).
2. Retry once.
3. If the retry also fails, implement exponential backoff with a configurable maximum number of retries.

Caution

Do not implement a tight retry loop on 503 errors. Repeated rapid requests during an overload condition will worsen the situation and may result in temporary blocking.

Related Resources

• Developer Overview
• API Authentication
• Error Codes