Rate Limits

ApiBiblia uses rate limiting to ensure fair usage and API stability.

Limits by Plan

Plan	Requests/Minute	Requests/Day
Free	30	1,000
Pro	100	10,000
Enterprise	500	Unlimited

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 25
X-RateLimit-Reset: 1699574400

Header	Description
X-RateLimit-Limit	Max requests per minute
X-RateLimit-Remaining	Remaining requests in window
X-RateLimit-Reset	Unix timestamp when limit resets

Rate Limit Exceeded

When you exceed the rate limit, you'll receive a 429 response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "retry_after": 45
  }
}

The retry_after field indicates seconds until you can retry.

Best Practices

1. Cache Responses

Bible content doesn't change frequently. Cache responses to reduce API calls:

const cache = new Map();

async function getVerse(ref) {
  const cacheKey = `verse:${ref}`;

  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const response = await fetch(`/v1/passage?ref=${ref}`);
  const data = await response.json();

  cache.set(cacheKey, data);
  return data;
}

2. Batch Requests

Instead of fetching verses one by one, use ranges:

# Bad: Multiple requests
curl "/v1/passage?ref=Romans 8:28"
curl "/v1/passage?ref=Romans 8:29"
curl "/v1/passage?ref=Romans 8:30"

# Good: Single request
curl "/v1/passage?ref=Romans 8:28-30"

3. Implement Exponential Backoff

When rate limited, use exponential backoff:

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') || Math.pow(2, i);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

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

4. Monitor Usage

Check your remaining quota before making requests:

const response = await fetch('/v1/versions', { headers });
const remaining = response.headers.get('X-RateLimit-Remaining');

if (remaining < 5) {
  console.warn('Rate limit nearly exhausted');
}

Need Higher Limits?

If you need higher rate limits:

• Pro Plan: 100 req/min, 10,000 req/day
• Enterprise: Custom limits available

View Pricing