Skip to main content

Rate Limits

Rate limits ensure fair usage and protect the API from abuse.

Rate Limit Tiers

PlanRequests/MonthRate Limit
Free20010/min
Developer50,00060/min
Pro150,000300/min
Enterprise500,0001,000/min; availability by arrangement

These are the currently configured default windows, enforced per API key. Account or key overrides and endpoint-specific limits may differ; response headers are authoritative. Monthly request units are shared across the organization, including REST, MCP, and scheduled checks. Rate admission and monthly quota are separate limits. WHOIS also has a daily admission limit.

Domain Monitoring Limits

Each watch monitors one endpoint for one domain. Watch counts and minimum intervals depend on your plan; the selected endpoint must also be available on that plan. History stays private to your organization.

PlanWatchesMinimum Interval
Free5Daily
Developer5030 minutes
Pro2505 minutes

Create a watch with POST /v1/watches, including endpoint_id, optional endpoint_params, interval_minutes, and the json_diff or status_change alert strategy. Read snapshots, changes, and alerts under /v1/watches/:id. Create separate watches to monitor different endpoints on the same domain.

Most analysis calls use one request unit per call. Uncached ping and traceroute probes use one unit per requested zone; cached results and status polls use one unit. Scheduled checks share your monthly request allowance. Free daily DNS and certificate watches do not unlock higher-tier endpoints. Enterprise is coming soon; contact us to discuss requirements.

Rate Limit Headers

Responses that reach rate-limit admission include headers to track the current window:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704067200
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current time window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the rate limit window resets
Retry-AfterSeconds to wait before retrying; may appear on 429 and transient 503 responses

Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests status code with a Retry-After header indicating when you can retry.

A 429 with QUOTA_EXCEEDED is different: short retries cannot replenish a monthly allowance. Inspect error.code and wait for the quota reset or adjust the allowance. See billing usage and the Monitoring API.

429 Response
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 60,
      "limit": 60,
      "window_seconds": 60
    }
  },
  "request_id": "req_abc123"
}

Reading Rate Limit Headers

Monitor the rate limit headers to track your usage. Bound retries so exhausted quotas cannot leave your application waiting indefinitely:

JavaScript
async function fetchWithRateLimit(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429 || attempt === maxRetries) {
      return response;
    }
    const failure = await response.clone().json().catch(() => null);
    if (failure?.error?.code === 'QUOTA_EXCEEDED') return response;
    const retryAfter = Number(response.headers.get('Retry-After'));
    const delay = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : 1000 * 2 ** attempt;
    await new Promise(resolve => setTimeout(resolve, delay));
  }
}

Exponential Backoff

For production applications, implement exponential backoff with jitter to avoid the thundering herd problem:

JavaScript
async function fetchWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }
    const failure = await response.clone().json().catch(() => null);
    if (failure?.error?.code === 'QUOTA_EXCEEDED') return response;

    // Exponential backoff: 1s, 2s, 4s, 8s, 16s
    const baseDelay = Math.pow(2, attempt) * 1000;
    // Add jitter (0-1000ms) to prevent synchronized retries
    const jitter = Math.random() * 1000;
    const retryAfter = Number(response.headers.get('Retry-After'));
    const serverDelay = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000 : 0;
    const delay = Math.max(baseDelay + jitter, serverDelay);

    console.log(`Attempt ${attempt + 1} failed. Retrying in ${delay}ms...`);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Max retries exceeded');
}

Best Practices

  • •Monitor remaining requests - Check X-RateLimit-Remaining and slow down before hitting limits
  • •Cache responses - Store API responses locally to reduce unnecessary requests
  • •Use composite endpoints - Use domain intelligence report to combine multiple lookups into one request
  • •Implement circuit breakers - Prevent cascading failures by temporarily stopping requests when errors spike
  • •Log rate limit events - Track when limits are hit for debugging and capacity planning

Need Higher Limits?

Upgrade your plan for higher rate limits or contact us for enterprise pricing.

API Rate Limits, Quotas & 429 Retry Handling | EdgeDNS