Skip to content

Rate limits

Teler limits how fast each account can send API requests, so calls stay reliable and the API stays fast for everyone. Limits apply per account and are shared by all API keys on that account.

  1. API request limit

    • Applies to: All /api/v1 endpoints, except the call endpoints below
    • Allowed: 15 requests per second, combined across these endpoints
  2. Call initiation limit

    • Applies to:
      • POST /api/v1/voice/calls/initiate
      • POST /api/v1/calls/initiate (deprecated)
      • POST /api/v1/voice/calls/{id}/transfer
    • Allowed: 3 requests per second combined across all three endpoints. For example, 2 initiates and 1 transfer in the same second use up the whole limit.

The call endpoints have their own limit and don’t count toward the API request limit.

Teler responds with 429 Too Many Requests. The Retry-After header gives the number of seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{
"success": false,
"message": "API rate limit reached for this account. Please try again in 1 second."
}

For the call initiation limit, the message is “Call rate limit reached for this account. Please try again in 1 second.”

Wait for the number of seconds in Retry-After, then send the same request again. A small random delay keeps parallel workers from retrying at the same moment.

Retry any /api/v1 request that returns 429:

import random
import time
import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.frejun.ai/api/v1"
def api_request(method, path, max_attempts=5, **kwargs):
for attempt in range(1, max_attempts + 1):
response = requests.request(method, BASE_URL + path, headers={"X-API-Key": API_KEY}, timeout=10, **kwargs)
if response.status_code != 429 or attempt == max_attempts:
return response
wait = int(response.headers.get("Retry-After", 1))
time.sleep(wait + random.random() * 0.5)
response = api_request("GET", "/voice/apps")

Pace calls to 3 per second, and retry any call that returns 429. A 429 means the call was not placed, so retrying it can’t dial the same number twice:

import random
import time
import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.frejun.ai/api/v1"
CALLS_PER_SECOND = 3
def initiate_call(payload, max_attempts=5):
for attempt in range(1, max_attempts + 1):
response = requests.post(BASE_URL + "/voice/calls/initiate", headers={"X-API-Key": API_KEY}, json=payload, timeout=10)
if response.status_code != 429 or attempt == max_attempts:
return response
wait = int(response.headers.get("Retry-After", 1))
time.sleep(wait + random.random() * 0.5)
for to_number in numbers:
response = initiate_call({
"from_number": "+91XXXXXXXXXX",
"to_number": to_number,
"flow_url": "https://example.com/flow",
"status_callback_url": "https://example.com/status",
})
print(to_number, response.status_code)
time.sleep(1 / CALLS_PER_SECOND) # stay under the limit; the retry above is the fallback

Only retry 429s this way. If a call times out or returns 5xx, it may already have been placed; follow Idempotency & retries.

  1. Use Retry-After. Decide how long to wait based on Retry-After; don’t parse the message text as it may change.
  2. Spread requests out. Limits are counted over a rolling second, so a steady rate works better than bursts.
  3. Plan for combined traffic. Every service and API key on the account shares the same limits.