Understanding API Rate Limits on VerseDB

VerseDB limits how many API requests you can make per hour. Limits are tiered by subscription and scoped by request type (read vs write).

Hourly Limits#

Search endpoints (like GET /api/series?q=spider-man) count against the read budget — there's no separate search pool.

Rate Limit Headers#

Every API response includes:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247

On a 429 response, the server also sends Retry-After (seconds to wait) and X-RateLimit-Reset (Unix timestamp of the reset).

fetch('https://versedb.com/api/series/123', {
  headers: { Authorization: 'Bearer YOUR_TOKEN' }
}).then(res => {
  console.log('Remaining:', res.headers.get('X-RateLimit-Remaining'));
  return res.json();
});

When You Hit the Limit#

A 429 Too Many Requests response:

{
  "message": "Too Many Attempts.",
  "retry_after": 3600
}

Stop sending requests and wait Retry-After seconds before retrying. Don't keep hitting the endpoint — it just delays recovery.

Staying Under the Limit#

Cache infrequently-changing data — publishers, creator bios, character info. Series and issue details are safe to cache for hours. Don't cache user data.

Implement exponential backoff when you hit 429:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    const retryAfter = parseInt(res.headers.get('Retry-After') || '60');
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  }
  throw new Error('Max retries exceeded');
}

Watch the headers — slow down when X-RateLimit-Remaining drops below ~10% of your limit.

Paginate efficiently — use limit and page instead of fetching everything at once.

Upgrade to PRO If#

• You regularly hit free-tier limits
• You run production integrations or automated tools
• You need relationship endpoints or market data (PRO-only)
• You need the extra headroom for burst workloads

PRO gives you ~3.3× the read and write budget plus access to PRO-only endpoints.