​
Rate Limits

To ensure fair usage and system stability, refile API implements rate limiting. This guide explains how rate limits work, how to monitor your usage, and best practices for working with these limits.

Our rate limits are designed to be generous for normal API usage patterns. For those building high-volume applications, we recommend implementing proper rate limit handling as described below.

​
Current Rate Limits

We currently apply a standard rate limit of 200 requests per minute for all API endpoints. This limit is applied based on your API key (for authenticated requests) or IP address (for unauthenticated requests).

If you’re not interested in the technical details, you don’t need to worry about rate limits unless you’re making a large number of requests in a short period.

​
Rate Limit Headers

When you make requests to the refile API, you’ll receive rate limit information in the response headers:

HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed in the current time window (200)
X-RateLimit-RemainingThe number of requests remaining in the current time window
X-RateLimit-ResetThe time at which the current rate limit window resets (Unix timestamp in seconds)

You can use these headers to monitor your rate limit status and implement appropriate request handling strategies in your applications.

​
Example Response Headers

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 198
X-RateLimit-Reset: 1682738400

​
Rate Limit Exceeded

If you exceed the rate limit, the API will respond with a 429 Too Many Requests HTTP status code and the following JSON body:

{
	"error": "Too many requests",
	"limit": 200,
	"reset": 1682738400
}

​
Best Practices

To avoid hitting rate limits, consider the following best practices:

​
1. Monitor Your Usage

Monitor the rate limit headers in API responses to track your remaining request quota. This allows you to adjust your request rate if necessary.

​
2. Implement Backoff Strategies

When you receive a 429 response, implement an exponential backoff strategy:

const backoff = (retryCount) => Math.pow(2, retryCount) * 1000; // 1s, 2s, 4s, 8s, etc.

async function makeRequestWithBackoff(url, options, retryCount = 0) {
	try {
		const response = await fetch(url, options);

		if (response.status === 429 && retryCount < 5) {
			const resetData = await response.json();
			const waitTime = backoff(retryCount);

			console.log(`Rate limited. Retrying in ${waitTime}ms`);
			await new Promise((resolve) => setTimeout(resolve, waitTime));

			return makeRequestWithBackoff(url, options, retryCount + 1);
		}

		return response;
	} catch (error) {
		console.error("Request failed:", error);
		throw error;
	}
}

​
3. Queue and Batch Requests

If your application needs to make many requests, consider queueing them and processing them at a controlled rate. You can also batch operations where possible to reduce the number of API calls.

​
Need Higher Limits?

If you require higher rate limits for your application, please contact us at help@refile.co to discuss your needs.