Skip to main content
The Musique API implements rate limiting to ensure fair usage and maintain service stability for all partners.

​
Default Limits

WindowLimitDescription
Per Minute100 requestsBurst limit for short operations
Per Hour1,000 requestsStandard operational limit
Per Day10,000 requestsDaily quota
Higher limits are available for Enterprise partners. Contact [email protected] to discuss your needs.

​
Rate Limit Headers

All API responses include rate limit information in the headers: 
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 77
X-RateLimit-Reset: 1705762440
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the limit resets

​
Exceeded Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 42 seconds.",
    "type": "rate_limit_error",
    "retryAfter": 42
  }
}
The response also includes a Retry-After header indicating when you can retry.

​
Handling Rate Limits

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    // Check remaining quota
    const remaining = response.headers.get('X-RateLimit-Remaining');
    if (remaining && parseInt(remaining) < 10) {
      console.warn(`Low rate limit: ${remaining} requests remaining`);
    }
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Waiting ${retryAfter}s...`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

​
Best Practices

Implement Backoff

Use exponential backoff when retrying failed requests. Start with 1 second and double each retry.

Monitor Usage

Track your rate limit consumption via the /api/integration/limits endpoint and headers.

Cache Responses

Cache GET responses where appropriate to reduce API calls. Audio metadata rarely changes.

Batch Operations

Use broadcast sends to multiple locations in a single request instead of individual calls.

​
Check Your Limits

Use the Rate Limits endpoint to check your current usage: 
curl https://api.musique.app/api/integration/limits \
  -H "X-API-Key: msk_live_1234567890abcdef"
Response: 
{
  "limits": {
    "perMinute": 100,
    "perHour": 1000,
    "perDay": 10000
  },
  "usage": {
    "perMinute": 23,
    "perHour": 347,
    "perDay": 2150
  },
  "remaining": {
    "perMinute": 77,
    "perHour": 653,
    "perDay": 7850
  }
}