Rate Limiting

Rate Limit Overview

The BreakBlocks API implements rate limiting to ensure fair access and prevent abuse. Rate limits are applied on a per-account basis.

Rate Limit Tiers

Rate Limit Headers

Each response includes headers showing your current rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704725400

X-RateLimit-Reset contains a Unix timestamp indicating when your rate limit will reset.

What Happens When Rate Limit is Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests status code:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Reset: 1704725400

{
  "success": false,
  "message": "Rate limit exceeded. Try again in 45 seconds."
}

Exempt Endpoints

The following endpoints have relaxed rate limits and are exempt from standard throttling:

• /metadata/* - Version, country, and region metadata (1 request per second limit)

Handling Rate Limits

When you receive a 429 response, check the Retry-After header and wait that many seconds before retrying:

// JavaScript with retry logic
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }
  
  throw new Error('Max retries exceeded');
}

const data = await fetchWithRetry('https://api.breakblocks.com/api/v0.1/servers/find?limit=10');

Best Practices

• Monitor Headers: Always check X-RateLimit-Remaining to avoid hitting limits
• Implement Backoff: Use exponential backoff when retrying failed requests
• Cache Results: Cache API responses locally to reduce requests
• Batch Requests: Combine multiple queries into single requests when possible
• Use API Keys: Authenticate with an API key to get higher rate limits
• Lazy Loading: Load data on-demand rather than pre-fetching everything

Throttling Strategy

For batch operations, implement controlled throttling to stay within limits:

// JavaScript - Process servers with delay
async function processServersWithThrottle(ips, delayMs = 500) {
  for (const ip of ips) {
    const response = await fetch(`https://api.breakblocks.com/api/v0.1/status/ping/${ip}/25565`);
    const data = await response.json();
    console.log(data);
    
    // Wait between requests to avoid rate limit
    await new Promise(resolve => setTimeout(resolve, delayMs));
  }
}

// Process 1 server every 500ms (120 servers/minute = well under 60/minute limit)
await processServersWithThrottle(serverList, 500);

Higher Limits

If you need higher rate limits, consider:

• Patreon Membership: Support development and get unlimited requests
• Contact Support: Use our contact form for enterprise rate limit increases