This document will help you understand how rate limiting works for our API and how to work within the rate limits effectively.
What is Rate Limiting?
Rate limiting is a technique used to control the number of requests a user can make to our API in a given time period. This ensures fair usage among all users and helps maintain the performance and reliability of the service.
Rate Limit Details
Rate Limit:
Maximum Requests: 100 requests
Time Window: 60 seconds
This means you can make up to 100 requests per minute.
Rate limit error
If you exceed the rate limit, you will receive a 429 Too Many Requests response. This response indicates that you need to wait before making more requests.
Example Response for Rate Limit Exceedance:
{ statusCode: 429, message:"ThrottlerException: Too Many Requests}Rate Limit Headers
To help you manage your request rate, the API provides the following headers in every response:
X-RateLimit-Limit: The maximum number of requests allowed in the current time window.
X-RateLimit-Remaining: The number of requests remaining in the current time window.
X-RateLimit-Reset: The number of seconds until the rate limit resets.
Example Headers:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 75 X-RateLimit-Reset: 30
How to avoid rate limit errors
Monitor Rate Limit Headers: Check the X-RateLimit-Remaining and X-RateLimit-Reset headers to understand how many requests you have left and when the limit will reset.
Implement Exponential Backoff: If you receive a 429 Too Many Requests response, implement a delay before retrying. For example, wait for a few seconds and then retry the request.
Graceful Handling of Rate Limits: Implement error handling in your application to gracefully handle 429 responses. Provide meaningful messages to your users, informing them about the rate limit and suggesting they retry later.
Example Scenario
Let's say you are fetching user data from the API, and you have a script that runs every second to fetch this data. If your script runs 100 times in 60 seconds, you will hit the rate limit. To avoid this, you can adjust the frequency of your requests or implement caching to reduce the number of calls.
Example Python Code to Check Rate Limit Headers:
import requestsresponse = requests.get('https://api.app.forward-earth.com.com/user')print(response.headers['X-RateLimit-Limit']) # 100print(response.headers['X-RateLimit-Remaining']) # 75print(response.headers['X-RateLimit-Reset']) # 30By following these guidelines, you can effectively manage your usage of the API and ensure that you stay within the rate limits. If you have any questions or need further assistance, please contact our support team.