ZTLayer Logo
Start Building

Rate Limits & Distributed Counters

ZTLayer enforces rate limits in two distinct areas: Management API Limits (for programmatic control of your rules/dashboard) and Edge Traffic Limits (for protecting your application from DDoS and abuse).

1. Edge Traffic Rate Limiting (Your Application)

Edge Rate Limiting is a core feature of ZTLayer that protects your infrastructure from volumetric Layer 7 attacks, credential stuffing, and aggressive scraping.

How Distributed Counters Work

ZTLayer uses a low-latency, globally distributed Redis-backed counter system. When a request hits an edge node in Tokyo, and the next request hits a node in Frankfurt, the counters are synchronized within milliseconds.

Configuring Edge Rate Limits

You can configure rate limits globally or per-route using the SDK.

// Next.js Edge Middleware Example
import { ZTLayer } from '@ztlayer/nextjs';
 
const security = new ZTLayer({
  apiKey: process.env.ZTLAYER_API_KEY,
  rateLimit: {
    // Global limit: 1000 requests per 10 minutes per IP
    global: {
      max: 1000,
      windowMs: 10 * 60 * 1000, 
    },
    // Strict limit for authentication routes
    routes: {
      '/api/auth/login': {
        max: 5, // 5 attempts
        windowMs: 60 * 1000, // per 1 minute
      }
    }
  }
});

Client Headers

When ZTLayer intercepts traffic heading to your app, it automatically appends informational headers to the response, allowing your frontend to react gracefully:

  • X-RateLimit-Limit: The configured maximum requests.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: Unix timestamp indicating when the counter resets.

2. Management API Limits (Dashboard)

To ensure the stability of the platform for all users, ZTLayer enforces rate limits on our REST Management APIs (used for CI/CD automation or retrieving analytics).

| Plan | Limit (Req/Min) | Limit (Req/Hour) | Burst Allowance | |------|-----------------|------------------|-----------------| | Free | 60 | 1,000 | No | | Pro | 300 | 10,000 | Yes (10% overage) | | Enterprise | Custom | Custom | Unlimited |

Handling Rate Limits (HTTP 429)

If your automated scripts exceed the Management API limit, ZTLayer will return an HTTP 429 Too Many Requests response.

The 429 response includes a Retry-After header indicating the number of seconds your client must wait before making another request.

Best Practice: Exponential Backoff Retry Logic

When integrating the ZTLayer Management API into your CI/CD pipelines, implement an exponential backoff strategy:

// Node.js Management API Retry Example
const fetchWithRetry = async (url, options, retries = 3) => {
  const res = await fetch(url, options);
  
  if (res.status === 429 && retries > 0) {
    // Parse Retry-After or default to 2 seconds
    const retryAfter = res.headers.get('Retry-After');
    const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : 2000;
    
    console.warn(`Rate limited. Retrying in ${delay}ms...`);
    await new Promise(resolve => setTimeout(resolve, delay));
    
    return fetchWithRetry(url, options, retries - 1);
  }
  
  if (!res.ok) {
    throw new Error(`API Error: ${res.status}`);
  }
  
  return res.json();
};
 
// Usage
const metrics = await fetchWithRetry('https://api.ztlayer.online/v1/metrics', {
  headers: { 'Authorization': `Bearer ${process.env.ZTLAYER_API_KEY}` }
});

Next Steps