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.
Limits
Section titled “Limits”-
API request limit
- Applies to: All /api/v1 endpoints, except the call endpoints below
- Allowed: 15 requests per second, combined across these endpoints
-
Call initiation limit
- Applies to:
POST /api/v1/voice/calls/initiatePOST /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.
- Applies to:
The call endpoints have their own limit and don’t count toward the API request limit.
When you hit a limit
Section titled “When you hit a 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 RequestsRetry-After: 1Content-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.”
Handling 429s
Section titled “Handling 429s”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.
API rate limit
Section titled “API rate limit”Retry any /api/v1 request that returns 429:
import randomimport 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")Call initiation rate limit
Section titled “Call initiation rate limit”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 randomimport 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 fallbackOnly retry 429s this way. If a call times out or returns 5xx, it may already have been placed; follow Idempotency & retries.
Best practices
Section titled “Best practices”- Use Retry-After. Decide how long to wait based on Retry-After; don’t parse the message text as it may change.
- Spread requests out. Limits are counted over a rolling second, so a steady rate works better than bursts.
- Plan for combined traffic. Every service and API key on the account shares the same limits.