Skip to main content

Overview

BeatPass uses route-specific rate limiting via Laravel’s throttle middleware. Different endpoint groups have different limits based on their resource intensity and expected usage patterns.

Route-Specific Limits

Producer Intelligence

Updated December 2025 — Rate limits increased for cached endpoints.

Leaderboards

600/min /producer-intelligence/leaderboard — Cached responses (~25ms response time).
120/min /producer-intelligence/tracks/growth-batch — Process up to 100 tracks per request.
1200/min /producer-intelligence/track/{id}/growth — Prefer batch endpoint for multiple tracks.
500/min Authenticated dashboard and analytics endpoints.
120/min Rate-limited for performance optimization.

Legacy Endpoints

Deprecated: /users/{user}/producer-dashboard is limited to 60/min and will be removed. Migrate to producer-intelligence endpoints.

Authentication

Authentication attempts are limited to prevent brute force attacks:

Login Attempts

5/min per IP

Password Reset

3/min per email

2FA Verification

5/min per session

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

429 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 Retry-After header for wait duration.
3

Implement Backoff

Use exponential backoff for retries.
4

Resume Carefully

Resume with reduced frequency.

Best Practices

Optimize Request Patterns

The Producer Intelligence API provides batch endpoints:
POST /producer-intelligence/tracks/growth-batch
Handles up to 100 tracks per request instead of individual calls.
Analytics data doesn’t change frequently. Cache responses for 5-15 minutes.
Use /producer-intelligence/progress-data for combined dashboard data instead of multiple calls.
Request appropriate page sizes. Don’t fetch more data than needed.

Exponential Backoff

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 intervals of 30+ seconds. Leaderboard data is cached for 5 minutes.
Problem: Calling /track/{id}/growth for each track individually.Solution: Use the batch endpoint /tracks/growth-batch for up to 100 tracks per request.
Problem: Firing many analytics requests simultaneously.Solution: Use /producer-intelligence/progress-data for consolidated dashboard data.
Problem: Sending a request on every keystroke.Solution: Debounce input by 300ms+ before triggering search.

Rate Limits by Feature

Low-Intensity Endpoints (No explicit throttle)

These endpoints use global defaults:
  • Track/album/artist listing and details
  • Playlist operations
  • User profile data
  • Genre and tag lookups

High-Intensity Endpoints (Throttled)

These have explicit rate limits:

Producer Intelligence

Heavy computation for XP, achievements, and rankings.

Social Analytics

Complex queries across social graph.

Legacy Dashboard

Deprecated — encouraging migration to new APIs.

Real-time Analytics

Database-intensive live data queries.

Error Recovery

When you hit a rate limit:
  1. Don’t retry immediately - This wastes your remaining quota
  2. Log the incident - Track which endpoints are hitting limits
  3. Review access patterns - Identify optimization opportunities
  4. Contact support - If legitimate usage requires higher limits

Caching Configuration

BeatPass uses centralized cache TTL (Time-To-Live) configuration for consistent caching behavior across the platform. This ensures predictable data freshness while optimizing performance.

Cache TTL Values

Dashboard Overview

15 min TTL Producer dashboard statistics

Real-time Metrics

1 min TTL Live engagement data

Development Note

When developing integrations, account for these cache windows in your data synchronization logic. Real-time data should not be polled more frequently than the cache TTL.

Next Steps

Last modified on December 5, 2025