Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

BlockDB enforces account-wide limits so traffic stays fair and the platform remains stable. Your subscription defines a single requests-per-second (RPS) ceiling and a single compute unit (CU) usage allowance for the billing period. Those limits are shared by every API key on the account: there is no per-key RPS budget, no per-key CU pool, and no way to split or “distribute” rate or usage across keys.
Rate limiting is measured in requests per second (RPS). GET /usage returns rate_limit_rps and your CU fields (cu_used, cu_limit, cu_remaining) for the account—the same values apply no matter which of your keys (up to five) you use.
Using multiple API keys does not multiply your RPS or your monthly CU budget. If two services each send traffic at the account RPS cap, they contend for the same shared limit. Plan concurrency and backoff accordingly.

​
API keys and shared limits

You can create up to five keys in dashboard.blockdb.io for rotation (old vs new), separate environments (e.g. staging vs production in your own systems), or blast-radius control (revoke one key without rotating everything). Those are operational choices—not a mechanism to assign different RPS or CU to each key. BlockDB does not offer per-key rate or usage allocation.
Example: two keys, one shared account limit
# Both keys authenticate different callers but draw from the same RPS and CU pool.
Authorization: Bearer $BLOCKDB_API_KEY_PROD
Authorization: Bearer $BLOCKDB_API_KEY_STAGING
# Shared: rate_limit_rps and monthly CU (see /usage)

​
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, typical Historic REST API response times look like:
  • Mean (average): 300-500 ms
  • p99: around 900 ms
Figures are indicative and vary by endpoint, payload size, and region. Latency targets assume you’re staying within your configured RPS limits. Sustained over-limit traffic may experience higher latency and eventual rate limiting.

​
Latency and routing (not separate quotas)

BlockDB may route you to a nearby edge or region for lower latency (for example via GeoDNS). That routing does not create separate RPS or CU pools per region or per key. Your account RPS and CU limits always apply the same way.

​
Key rotation and dashboard

In dashboard.blockdb.io you can create, label, and revoke keys (up to five active). You cannot assign a different RPS or CU cap to an individual key—limits stay at the account level. Use GET /usage to monitor rate_limit_rps and CU usage for the whole account, not per key.
Keep API keys secure and never commit them to version control. Rotate keys regularly for security best practices.

​
See Also

Last modified on April 22, 2026