Rate Limits

Request quotas and throttling policies for the Melonly API

Requests are managed on a fixed quota system with different limits based on your server configuration.

---

Standard Rate Limits

All servers receive a base allocation of API requests with standard throttling policies.

Header	Value	Meaning
X-RateLimit-Limit	1000	Maximum requests allowed per hour
X-RateLimit-Remaining	847	Requests remaining in current window
X-RateLimit-Used	153	Requests consumed in current window
X-RateLimit-Reset	3600	Seconds until rate limit window resets
Retry-After	1	Seconds to wait before next request (when rate limited)

Rate limits are calculated per server on every request. Each server operates independently with its own quota allocation.

---

Premium Rate Limits

Servers with premium subscriptions receive enhanced rate limits and priority processing.

Header	Value	Meaning
X-RateLimit-Limit	5000	Maximum requests allowed per hour
X-RateLimit-Remaining	4723	Requests remaining in current window
X-RateLimit-Used	277	Requests consumed in current window
X-RateLimit-Reset	2890	Seconds until rate limit window resets
X-RateLimit-Window	3600	Duration of rate limit window (always 1 hour)
Retry-After	1	Seconds to wait before next request (when rate limited)

Premium limits are subject to fair usage policies. Sustained high-volume usage may require additional rate limit discussions.

---

Rate Limit Headers

All API responses include rate limiting headers to help you manage request flow:

Standard Response

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Used: 153
X-RateLimit-Reset: 3600
Content-Type: application/json

{
  "id": "server_12345",
  "name": "Example Server"
}

Rate Limited Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Used: 1000
X-RateLimit-Reset: 2847
Retry-After: 1
Content-Type: application/json

{
  "error": "rate limit exceeded"
}

---

Handling Rate Limits

JavaScript

async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'Authorization': 'Bearer your_token',
      ...options.headers
    }
  });
  
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
    
    // Wait and retry
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return apiRequest(url, options);
  }
  
  return response;
}

---

Best Practices

Monitor Headers

Always check rate limit headers in responses to proactively manage request flow

Implement Backoff

Use exponential backoff strategies for handling 429 responses

Batch Operations

Group related requests and use pagination efficiently to minimize API calls

Cache Responses

Cache frequently accessed data to reduce unnecessary API requests

Rate Limit Planning: For high-volume integrations, monitor your usage patterns and consider implementing request queuing to stay within limits consistently.