Rate limits
Limits apply to each API key, not to your workspace or your IP address.
| Limit | Value |
|---|---|
| Requests per key | 60 per minute |
| Extract candidate details | 10 per minute, because each file is read by a model |
| Get a job's counts | 30 per minute, because it reads a job's whole application history |
| Get an interview's report | 30 per minute, the same limit as a job's counts |
| CV files per extract request | 10 |
| Candidates per submit request | 50 |
These are the starting values for v1 and may change before launch. The response headers are always the source of truth for your key.
Headers
Successful responses report where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Seconds until the window resets. |
When you go over, the response is 429 rate_limited with a Retry-After header, in seconds.
Backing off
Wait for Retry-After, then retry. This helper does that and gives up after three attempts. It is safe to use with Submit candidates as long as you reuse the same Idempotency-Key.
- cURL
- Node.js
- Python
# curl retries 429 and 5xx on its own, and honours Retry-After.
curl --retry 3 -X POST https://api.tarkflo.com/v1/candidates/submit \
-H "Authorization: Bearer $TARKFLO_API_KEY" \
-H "Idempotency-Key: 6f0a2d4e-9c1b-4f7a-8e35-1b2d3c4e5f60" \
-H "Content-Type: application/json" \
-d @batch.json
async function withRetry(makeRequest, attempts = 3) {
for (let attempt = 1; ; attempt++) {
const res = await makeRequest();
const retryable = res.status === 429 || res.status >= 500;
if (!retryable || attempt === attempts) return res;
const wait = Number(res.headers.get("Retry-After")) || 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
}
}
import time
import requests
def with_retry(make_request, attempts=3):
for attempt in range(1, attempts + 1):
res = make_request()
retryable = res.status_code == 429 or res.status_code >= 500
if not retryable or attempt == attempts:
return res
wait = int(res.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)