Skip to main content

​
Overview

BlockDB enforces rate limits to ensure fair usage and system stability. Rate limits are configured per API key and can be distributed across multiple keys for load balancing. All API responses include rate limit headers that indicate your current quota status.
Rate limits are measured in requests per second (RPS). Your total quota can be distributed across multiple API keys, each bound to a specific region for optimal performance.

​
Rate Limit Configuration

​
API Key Management

Rate limits are configured per API key through the BlockDB Admin Panel. Each API key can be assigned:
  • Portion of global rate limit: Distribute your total RPS quota across multiple keys
  • Regional binding: Assign keys to specific regions (US, EU, AP) to optimize latency and avoid cross-region synchronization
# Key 1: 100 RPS - US region
Authorization: Bearer key_us_100rps

# Key 2: 300 RPS - EU region  
Authorization: Bearer key_eu_300rps

# Key 3: 600 RPS - AP region  
Authorization: Bearer key_ap_600rps

# Total: 1000 RPS distributed across regions

​
Burst Tolerance

BlockDB tolerates short bursts up to 1.5x your configured RPS for up to 10 seconds. This allows for traffic spikes without immediate rate limiting, while maintaining overall system stability.
Sustained traffic above your RPS limit will trigger rate limiting. Use burst capacity for temporary spikes, not sustained high-volume traffic.

​
Rate Limit Responses

​
429 Too Many Requests

When you exceed your rate limit, the API returns 429 with a Retry-After header:
Error
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": "Limit: <CONFIGURED_RPS> requests/second. Retry after: <RETRY_AFTER>"
  }
}

​
Backoff Strategies

​
Exponential Backoff

Implement exponential backoff when receiving 429 responses: 
using System;
using System.Net.Http;
using System.Threading.Tasks;

public static async Task<HttpResponseMessage> RequestWithBackoffAsync(
    HttpClient client,
    Func<HttpRequestMessage> requestFactory,
    int maxRetries = 5)
{
    var delay = TimeSpan.FromSeconds(1);

    for (var attempt = 0; attempt < maxRetries; attempt++)
    {
        using var request = requestFactory();
        var response = await client.SendAsync(request);

        if (response.StatusCode == (System.Net.HttpStatusCode)429)
        {
            var retryAfterHeader = response.Headers.RetryAfter?.Delta ?? delay;
            await Task.Delay(retryAfterHeader);
            delay = retryAfterHeader;
            continue;
        }

        if (response.IsSuccessStatusCode || attempt == maxRetries - 1)
        {
            return response;
        }

        await Task.Delay(delay);
        delay = TimeSpan.FromMilliseconds(delay.TotalMilliseconds * 2);
    }

    throw new InvalidOperationException("Retries exhausted");
}

​
Best Practices

Implement request queuing for high-volume applications to smooth out request patterns.
Do not ignore 429 responses or retry immediately. Always respect the Retry-After header to avoid further rate limiting.

​
Performance Expectations

When staying within your rate limits, you can expect:
  • p50 latency: 20-50 ms (database response time)
  • p99 latency: 150-300 ms (database response time)
Latency targets assume you’re staying within your configured RPS limits. Sustained over-limit traffic may experience higher latency and eventual rate limiting.

​
Regional Considerations

BlockDB operates regional API gateways to optimize latency and performance. When configuring API keys:
  • US region: Optimized for North and South American traffic
  • EU region: Optimized for European traffic
  • AP region: Optimized for Asian traffic
Assign API keys to the region closest to your infrastructure to minimize latency. You can distribute your total RPS quota across multiple regional keys.
Traffic is automatically routed to the closest regional gateway via GeoDNS. Regional keys help ensure optimal performance and load distribution.

​
Key Rotation & Management

API keys are managed through the BlockDB Admin Panel:
  • Create keys: Generate new API keys with custom rate limits
  • Rotate keys: Revoke and regenerate keys for security
  • Monitor usage: Track rate limit consumption per key
  • Key expiration: Keys remain active for your subscription term (configurable by the user)
Keep API keys secure and never commit them to version control. Rotate keys regularly for security best practices.

​
See Also