> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musique.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understand API rate limits and how to handle them

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

## Default Limits

| Window     | Limit           | Description                      |
| ---------- | --------------- | -------------------------------- |
| Per Minute | 100 requests    | Burst limit for short operations |
| Per Hour   | 1,000 requests  | Standard operational limit       |
| Per Day    | 10,000 requests | Daily quota                      |

<Note>
  Higher limits are available for Enterprise partners. Contact [support@musique.app](mailto:support@musique.app) to discuss your needs.
</Note>

***

## Rate Limit Headers

All API responses include rate limit information in the headers:

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 77
X-RateLimit-Reset: 1705762440
```

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp when the limit resets           |

***

## Exceeded Limits

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "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

<CodeGroup>
  ```javascript Node.js theme={null}
  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');
  }
  ```

  ```python Python theme={null}
  import requests
  import time

  def make_request_with_retry(url, max_retries=3, **kwargs):
      for attempt in range(max_retries):
          response = requests.request(url=url, **kwargs)
          
          # Check remaining quota
          remaining = response.headers.get('X-RateLimit-Remaining')
          if remaining and int(remaining) < 10:
              print(f"Low rate limit: {remaining} requests remaining")
          
          if response.status_code == 429:
              retry_after = int(response.headers.get('Retry-After', 60))
              print(f"Rate limited. Waiting {retry_after}s...")
              time.sleep(retry_after)
              continue
          
          return response
      
      raise Exception('Max retries exceeded')
  ```
</CodeGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Implement Backoff" icon="clock-rotate-left">
    Use exponential backoff when retrying failed requests. Start with 1 second and double each retry.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Track your rate limit consumption via the `/api/integration/limits` endpoint and headers.
  </Card>

  <Card title="Cache Responses" icon="database">
    Cache GET responses where appropriate to reduce API calls. Audio metadata rarely changes.
  </Card>

  <Card title="Batch Operations" icon="layer-group">
    Use broadcast sends to multiple locations in a single request instead of individual calls.
  </Card>
</CardGroup>

***

## Check Your Limits

Use the [Rate Limits endpoint](/api-reference/system/rate-limits) to check your current usage:

```bash theme={null}
curl https://api.musique.app/api/integration/limits \
  -H "X-API-Key: msk_live_1234567890abcdef"
```

Response:

```json theme={null}
{
  "limits": {
    "perMinute": 100,
    "perHour": 1000,
    "perDay": 10000
  },
  "usage": {
    "perMinute": 23,
    "perHour": 347,
    "perDay": 2150
  },
  "remaining": {
    "perMinute": 77,
    "perHour": 653,
    "perDay": 7850
  }
}
```