Rate Limits
Understand throttling policies and optimize your API usage for production applications
Overview
The Taxu API implements rate limiting to ensure fair usage and maintain platform stability. Rate limits are applied per API key and calculated using a sliding window algorithm.
Generous Default Limits
Our default rate limits are designed to support most production applications without requiring upgrades. Monitor your usage in the Dashboard to ensure you stay within limits.
Rate Limit Tiers
Rate limits vary by account tier and endpoint type. All limits are applied per API key.
Standard
Default for all accounts
Professional
Higher limits for growing businesses
Enterprise
Custom limits for large-scale operations
Endpoint-Specific Limits
Some endpoints have different rate limits
| Endpoint Type | Standard Limit | Reason |
|---|---|---|
/v1/tax/efile | 10 req/min | IRS submission throttling |
/v1/documents/extract | 30 req/min | AI processing resources |
/v1/banking/accounts | 50 req/min | Bank data provider limits |
Rate Limit Response Headers
Every API response includes headers that show your current rate limit status:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the time window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the limit resets |
Retry-After | Seconds to wait before retrying (429 responses only) |
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1704067200
Content-Type: application/json
{
"status": "success",
"data": { ... }
}Handling Rate Limit Errors
When you exceed a rate limit, the API returns a 429 Too Many Requests error:
{
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded. Please retry after 12 seconds.",
"code": "rate_limit_exceeded",
"retry_after": 12
}
}Retry Logic Example
Implement exponential backoff with the Retry-After header:
async function makeRequestWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
continue;
}
if (response.ok) {
return await response.json();
}
throw new Error(`Request failed: ${response.status}`);
}
throw new Error('Max retries exceeded');
}
// Usage
const result = await makeRequestWithRetry('https://api.taxu.com/v1/tax/calculate', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_test_...',
'Content-Type': 'application/json'
},
body: JSON.stringify({ filingStatus: 'single', income: 75000 })
});Best Practices
Monitor rate limit headers
Track X-RateLimit-Remaining to proactively slow down requests before hitting limits
Implement exponential backoff
Use exponential backoff when retrying failed requests to avoid thundering herd problems
Cache responses when possible
Reduce API calls by caching data that doesn't change frequently
Use webhooks for async operations
Instead of polling, use webhooks to get notified when operations complete
Batch requests when supported
Use batch endpoints to perform multiple operations in a single request
Avoid tight polling loops
Repeatedly checking for updates can quickly exhaust your rate limit
Monitor Your Usage
View real-time rate limit metrics and usage analytics in your Dashboard