Rate Limits
Per-key sliding window rate limits, response headers, and how to handle 429 errors.
Rate Limits
Per-Key Limits
Every API key has a per-minute request cap set by your plan. The default cap is 600 requests per minute. This is a sliding window — Parseo averages requests over the last 60 seconds, not just the current minute boundary.
Response Headers
Every response includes rate limit status headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Your key's requests-per-minute cap |
X-RateLimit-Remaining | Requests available in the current window |
X-RateLimit-Reset | Unix timestamp when the window fully resets |
When you receive a 429 Too Many Requests, Parseo adds:
| Header | Description |
|---|---|
Retry-After | Seconds to wait before retrying |
Handling 429 Errors
Node.js
async function uploadWithRetry(file, apiKey, retries = 3) {
for (let i = 0; i < retries; i++) {
const res = await fetch('https://api.parseo.app/external/v1/invoices', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
body: file,
});
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60', 10);
await new Promise(r => setTimeout(r, retryAfter * 1000));
continue;
}
return res;
}
throw new Error('Rate limit retries exhausted');
}Python
import time, requests
def upload_with_retry(file_path, api_key, retries=3):
for i in range(retries):
with open(file_path, 'rb') as f:
res = requests.post(
'https://api.parseo.app/external/v1/invoices',
headers={'Authorization': f'Bearer {api_key}'},
files={'file': f}
)
if res.status_code == 429:
retry_after = int(res.headers.get('Retry-After', 60))
time.sleep(retry_after)
continue
return res
raise Exception('Rate limit retries exhausted')Burst Protection
Parseo uses a sliding window counter, meaning you can burst up to your full per-minute cap in a short window. However, if you fire all 600 requests in the first second, you will be throttled for the remainder of that minute.
Best practice: spread uploads evenly — e.g. 10 uploads/second for 60 seconds, not 600 at once.
Unauthenticated Rate Limit
Requests without a valid API key are limited to 20 requests per minute per IP. If your load balancer or CI system rotates source IPs, this limit applies per IP independently.