Skip to main content

​
Overview

The BeatPass API enforces to ensure fair usage and platform stability. Different endpoint categories have different limits based on their resource intensity.

​
Global Rate Limit

Global API Limit

300 requests/minute All API endpoints are subject to a global rate limit of 300 requests per minute per client. Route-specific limits below may impose stricter thresholds on individual endpoints.

​
Rate Limit Categories

Different endpoint categories have different rate limits. The API applies the most restrictive applicable limit.

General API Endpoints

Standard content endpoints (tracks, artists, albums, search, genres) are subject to the global rate limit.
Audio and image endpoints have stricter per-minute limits to prevent abuse.
Analytics and dashboard endpoints have dedicated rate limits appropriate for their resource intensity.
Endpoints that create or modify data (uploads, purchases, messages) have stricter limits.
Authentication endpoints have strict rate limits to prevent brute-force attacks. Excessive failed attempts will result in temporary lockout.

​
Rate Limit Format

Rate limits are expressed as requests per time window:
  • Requests: Maximum number of requests allowed
  • Window: Time period (typically 1 minute)
Example: “60 requests per minute” means you can make 60 requests within any 60-second window.

​
Rate Limit Headers

Responses include standard rate limit headers: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1700000060
​
X-RateLimit-Limit
integer
Maximum requests allowed in the current window.
​
X-RateLimit-Remaining
integer
Number of requests remaining in the current window.
​
X-RateLimit-Reset
unix timestamp
Unix timestamp when the rate limit window resets.

​
When Limits Are Exceeded

​
Response

HTTP/1.1 429 Too Many Requests
Retry-After: 60

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

​
Handling Rate Limits

1

Stop Requests

Immediately pause further requests to the limited endpoint.
2

Check Retry-After

Read the header for wait duration.
3

Implement Backoff

Use exponential backoff for retries.
4

Resume Carefully

Resume with reduced frequency.

​
Best Practices

​
Optimize Request Patterns

Where available, use batch endpoints to fetch multiple resources in a single request instead of individual calls.
Cache API responses locally to reduce redundant calls. Most data does not change frequently.
Request appropriate page sizes. Don’t fetch more data than needed.
For search-as-you-type features, debounce input by 300ms+ before triggering API calls.

​

async function fetchWithBackoff(url, options = {}, attempt = 1) {
  const maxAttempts = 5;
  
  const response = await fetch(url, options);
  
  if (response.status === 429 && attempt < maxAttempts) {
    const retryAfter = parseInt(response.headers.get('Retry-After')) || Math.pow(2, attempt);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return fetchWithBackoff(url, options, attempt + 1);
  }
  
  return response;
}

​
Monitoring Usage

​
Track Rate Limit Status

async function apiRequest(url, options) {
  const response = await fetch(url, options);
  
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const limit = response.headers.get('X-RateLimit-Limit');
  
  if (remaining && parseInt(remaining) < 10) {
    console.warn(`Rate limit warning: ${remaining}/${limit} remaining`);
  }
  
  return response;
}

​
Common Patterns That Trigger Limits

Problem: High frequency polling drains your quota.Solution: Use reasonable intervals (30+ seconds) and cache responses locally.
Problem: Fetching resources one at a time in a loop.Solution: Use batch endpoints where available, or paginated listing endpoints.
Problem: Firing many requests simultaneously.Solution: Stagger requests and use combined endpoints where available.

​
Error Recovery

When you hit a rate limit:
  1. Don’t retry immediately — This wastes your remaining quota
  2. Check the Retry-After header — Wait the specified duration
  3. Review access patterns — Identify optimization opportunities
  4. Contact support — If legitimate usage requires higher limits

​
Next Steps

API Reference

See all available endpoints.

Authentication

Understand API authentication.
Last modified on February 10, 2026