Rate Limiting
This guide explains our API rate limiting policy to help you build reliable and efficient applications. Understanding these limits is crucial for preventing service disruptions
Understanding API Rate Limiting
Rate limiting is a standard practice for APIs that controls the number of requests a user can make in a specific time frame. We implement it for two main reasons:
- Stability & Reliability: It protects our infrastructure from being overwhelmed by too many requests at once, ensuring the API remains stable and available for all users. ⚙️
- Fair Usage: It ensures that one user's high traffic doesn't negatively impact the experience of other users.
Our Rate Limit Policy
Our policy is designed to provide ample capacity for most applications. Rate limits will be applied separately for custom integrations and partner integrations.
This limit is applied on a fixed-window basis, meaning the counter resets at the end of each 30-second interval.
Checking Your Usage with Headers
To help you manage your request volume and avoid hitting the limit, we include the following HTTP headers in every API response. Monitoring these headers is the best way to stay within the allowed limits.
-
X-RateLimit-Limit
: The total number of requests allowed in the current window.- Example:
X-RateLimit-Limit: 75
- Example:
-
X-RateLimit-Remaining
: The number of requests you have left in the current window.- Example:
X-RateLimit-Remaining: 72
- Example:
-
X-RateLimit-Reset
: The Coordinated Universal Time (UTC) epoch timestamp indicating when the current rate limit window will reset. You can convert this timestamp to a human-readable date to know when your quota will be fully restored.- Example:
X-RateLimit-Reset: 1756285800
- Example:
Proactively checking the X-RateLimit-Remaining
header allows your application to slow down or pause requests as you approach the limit, preventing errors.
Handling "429 Too Many Requests" Errors
If you exceed the request limit within a 30-second window, the API will respond with an HTTP 429 Too Many Requests
status code.
When you receive a 429
error, the response will also include a Retry-After
header.
Retry-After
: The number of seconds you must wait before making another request. TheX-RateLimit-*
headers will also be present, showingX-RateLimit-Remaining: 0
.
Your application should be built to handle this error gracefully. Do not immediately retry the request. Instead, read the value of the Retry-After
header and wait for that duration before attempting the request again.
Pseudo-code Example
Here’s a basic example of how to handle a rate limit error:
response = make_api_request()
if response.status_code == 429:
# Get the wait time from the 'Retry-After' header
wait_seconds = response.headers['Retry-After']
print(f"Rate limit exceeded. Waiting for {wait_seconds} seconds.")
# Pause execution for the specified duration
sleep(wait_seconds)
# Retry the request
response = make_api_request()
process(response)
Best Practices & Recommendations
Follow these best practices to ensure your application works efficiently with our API. 🧑💻
-
Be Proactive, Not Reactive: Don't wait for a
429
error. Use theX-RateLimit-Remaining
header to dynamically control your request rate. For example, if the remaining count drops below a certain threshold (e.g., 10), slow down your requests or pause them until the window resets (indicated byX-RateLimit-Reset
). -
Implement Caching: If you frequently request the same data, cache it on your end. Storing responses locally can significantly reduce the number of API calls you need to make, improving performance and keeping you well within the rate limit.
-
Use Exponential Backoff: For handling transient network errors or
429
responses, a retry mechanism with exponential backoff is highly recommended. While you should always prioritize theRetry-After
header for429
errors, exponential backoff can be a robust fallback for other issues. -
Avoid Overlapping Requests: Making a high volume of concurrent or parallel requests can quickly exhaust your limit. If your application design requires concurrency, be sure to centrally monitor the
X-RateLimit-Remaining
value across all threads or processes to avoid exceeding the limit.
Updated 3 days ago