Rate Limits

Understanding API rate limits and usage tiers

To ensure fair usage and API stability, telco.dev enforces rate limits based on your subscription tier.

Rate Limit Tiers

How Rate Limits Work

Daily Limits

• Reset at midnight UTC each day
• Tracked per API key
• Shared across all endpoints

Per-Minute Limits

• Reset every 60 seconds
• Prevents burst abuse while allowing normal usage
• Each API call counts as 1 request

Rate Limit Headers

Every API response includes rate limit information in the headers:

Daily Rate Limit Headers

Per-Minute Rate Limit Headers

Example Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705449600
X-RateLimit-Minute-Limit: 6
X-RateLimit-Minute-Remaining: 4
X-RateLimit-Minute-Reset: 1705363260

Rate Limit Exceeded

When you exceed your rate limit, you'll receive a 429 Too Many Requests response.

Per-Minute Limit Exceeded

{
  "error": "rate_limited",
  "message": "Per-minute rate limit exceeded. Limit: 6/minute. Resets in 45 seconds.",
  "details": {
    "limit_type": "minute",
    "limit": 6,
    "remaining": 0,
    "reset": 1705363260
  }
}

Daily Limit Exceeded

{
  "error": "rate_limited",
  "message": "Daily rate limit exceeded. Limit: 100/day. Resets at 2025-01-16T00:00:00.000Z",
  "details": {
    "limit_type": "daily",
    "limit": 100,
    "remaining": 0,
    "reset": 1705449600
  }
}

Handling Rate Limits

Best Practices

1. Check headers after each request to monitor remaining quota
2. Implement exponential backoff when rate limited
3. Cache responses for frequently looked-up numbers
4. Batch requests where possible to reduce total calls

Example: Handling Rate Limits in JavaScript

async function lookupNumber(tn, apiKey) {
  const response = await fetch(
    `https://api.telco.dev/v1/lookup/${tn}`,
    { headers: { "X-API-Key": apiKey } }
  );

  // Check rate limit headers
  const remaining = response.headers.get("X-RateLimit-Remaining");
  const minuteRemaining = response.headers.get("X-RateLimit-Minute-Remaining");

  console.log(`Daily remaining: ${remaining}`);
  console.log(`Minute remaining: ${minuteRemaining}`);

  if (response.status === 429) {
    const data = await response.json();
    const resetTime = data.details.reset;
    const waitMs = (resetTime * 1000) - Date.now();

    console.log(`Rate limited. Waiting ${waitMs}ms...`);
    await new Promise(resolve => setTimeout(resolve, waitMs));

    // Retry the request
    return lookupNumber(tn, apiKey);
  }

  return response.json();
}

Upgrading Your Plan

If you need higher limits:

1. Go to your Dashboard
2. Click "Upgrade Plan"
3. Choose a plan that fits your needs
4. Your new limits take effect immediately