This documentation explains the rate limiting mechanisms for our API and how users can handle rate limits effectively. Rate limiting is enforced to prevent abuse and ensure fair usage of resources. Here, we define key terms related to rate limiting and provide an automated approach to handle rate limit errors.
Key Rate Limiting Terms
Retry-After
This header indicates the amount of time (in milliseconds) you must wait before sending another request. It is sent when you've exceeded your rate limit, indicating the cooldown period before you can retry the request.
X-Ratelimit-Consumed
This header indicates the number of API calls you have made within the current rate limit window. It increases each time you make a request.
X-Ratelimit-Remaining
This header indicates the number of API calls you can still make within the current rate limit window. It decreases with every request you send. If the value reaches 0, you have exhausted your quota for the current period.
Example Response Headers
{
"retry-after": "23284",
"x-ratelimit-consumed": "34",
"x-ratelimit-remaining": "166"
}
retry-after: 23284: The user has exceeded the allowed number of requests and should wait for 23284 milli-seconds before making another request.
x-ratelimit-consumed: 34: 34 requests have been made so far in the current rate limiting window.
x-ratelimit-remaining: 166: 166 requests can still be made before the user reaches their rate limit.
Rate Limiting Behavior
Rate Limit Windows
The API uses a time-based window (e.g., per minute, hour, or day) to track the number of API requests made. Each request consumes a certain portion of your quota, and the remaining quota is indicated by the x-ratelimit-remaining header.
Once your quota is exhausted (x-ratelimit-remaining = 0), you must wait until the window resets. The retry-after header tells you how long to wait before sending a new request.
Consumption and Reset
Each time you send a request:
The x-ratelimit-consumed counter increases by one.
The x-ratelimit-remaining counter decreases by one.
The reset occurs after the window period has elapsed, as indicated by the retry-after header. At that point, both x-ratelimit-consumed and x-ratelimit-remaining will be reset according to the new window.
Handling Rate Limit Exceeded
When your rate limit is exceeded, the API will respond with the following headers:
retry-after: A time period in milli-seconds that you must wait before retrying the request.
x-ratelimit-consumed: The number of requests made in the current window.
x-ratelimit-remaining: The remaining requests available in the current window.
If you receive a 429 Too Many Requests response (rate limit exceeded), you should check the retry-after header and wait for the specified time before retrying.
Automatically Handling Rate Limits
To handle the rate limit automatically, you can use the following approach:
JavaScript Snippets for Automatic Retry
Example 1: Using Axios Libraryconst axios = require('axios');
async function callApiWithRateLimitHandling(url, headers = {}) {
while (true) {
try {
const response = await axios.get(url, { headers });
return response.data; // Return the response data if successful
} catch (error) {
if (error.response && error.response.status === 429) {
const retryAfter = parseInt(error.response.headers['retry-after'], 10) || 0;
console.warn(`Rate limit exceeded. Retrying after ${retryAfter} ms...`);
await new Promise(resolve => setTimeout(resolve, retryAfter));
} else {
throw error; // Re-throw error if it's not related to rate limiting
}
}
}
}
// Example usage
const url = 'https://api.testlify.com/ping';
const headers = { Authorization: 'Bearer YOUR_API_KEY' };
callApiWithRateLimitHandling(url, headers)
.then(data => console.log(data))
.catch(error => console.error('API call failed:', error));
Example 2: Using Axios-Retry Library
const axios = require('axios');
const axiosRetry = require('axios-retry');
// Create an Axios instance
const axiosInstance = axios.create();
// Add retry logic with Axios-Retry
axiosRetry(axiosInstance, {
retries: 3, // Number of retry attempts
retryCondition: (error) => {
return error.response && error.response.status === 429; // Retry on 429 status code
},
retryDelay: (retryCount, error) => {
const retryAfter = parseInt(error.response.headers['retry-after'], 10) || 0;
console.warn(`Retry attempt ${retryCount}. Waiting for ${retryAfter} ms...`);
return retryAfter;
}
});
// Example usage
const url = 'https://api.testlify.com/ping';
const headers = { Authorization: 'Bearer YOUR_API_KEY' };
axiosInstance.get(url, { headers })
.then(response => console.log(response.data))
.catch(error => console.error('API call failed:', error));
Explanation
Milliseconds (ms) for retry-after: Ensures finer control over wait times before retrying the request.
await new Promise(resolve => setTimeout(resolve, retryAfter)): Ensures the program waits for the specified time.
axios-retry: Provides built-in retry logic with customizable conditions and delays.
429 status code: Indicates that the request has been throttled due to too many requests in a given timeframe.
Best Practices
Respect Rate Limits: Always check the x-ratelimit-remaining header to monitor how many requests you can make and adjust accordingly.
Retry Logic: Implement exponential backoff or other retry strategies to reduce the load on the API if you are hitting the rate limit frequently.
Efficient API Usage: Try to batch requests or optimize your queries to avoid unnecessary calls to the API.
Summary
The x-ratelimit-consumed and x-ratelimit-remaining headers are used to track the usage and remaining quota in the current rate limit window.
retry-after indicates how long you should wait before retrying a request once you hit the rate limit.
Use the provided JavaScript snippets to automatically handle rate limiting and retry the request after the appropriate waiting period.
By following these guidelines, you can ensure a smooth and efficient interaction with our API, even when rate limits are encountered.