Understanding API Rate Limits on VerseDB

What Are Rate Limits?

Rate limits help ensure fair use and performance for everyone accessing the VerseDB API. Your account has a set number of API calls it can make within an hour.

Rate Limits by User Tier

Types of Endpoints & Limits

Read-Only Endpoints

Free users: 300/hour
Pro users: 1000/hour

Applies to:

• GET /api/publishers, /api/series, /api/characters, etc.
• Viewing collections, wishlists, pull list, etc.

Write Operations

Free users: 150/hour
Pro users: 500/hour

Includes all POST, PUT, DELETE requests — such as updating your collection or pull list.

Search Endpoints

Free users: 60/hour
Pro users: 120/hour

Applies to:

• /api/characters/search
• /api/creators/search

Bulk Operations

Free users: 30/hour
Pro users: 60/hour

Used for batch actions or heavy-processing endpoints.

Rate Limit Headers

Every API response includes these headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1712869200

Header descriptions:

• X-RateLimit-Limit: Your hourly max
• X-RateLimit-Remaining: How many calls you have left
• X-RateLimit-Reset: When your limit resets (UNIX time)

What Happens if You Hit the Limit?

If you exceed your rate limit, you'll receive:

Status Code: 429 Too Many Requests

{
  "error": "Too Many Requests",
  "message": "API rate limit exceeded",
  "retry_after": 3600
}

Best Practices

• Cache frequent API results when possible
• Use bulk endpoints to reduce individual requests
• Handle 429 errors with exponential backoff
• Always check the rate limit headers in your responses
• Consider Pro access for higher and faster throughput