All guides
Guide
Rate limits and quotas
Every key has two ceilings: calls per hour and calls per calendar month. Whichever you reach first returns 429.
Plans
| Plan | Per hour | Per calendar month |
|---|---|---|
| Evaluation | 100 | 10,000 |
| Standard | 1,000 | 250,000 |
| Partner | 10,000 | No monthly cap |
A key you create in your dashboard starts on Evaluation. Moving to Standard or Partner is agreed with us, and we can also set a bespoke allowance on your key without moving you to a different plan. Usage is counted per key, so other partners never use up your allowance, and the count survives our deploys.
Headers
Every response to a request made with a valid key tells you where you stand, whatever its status: 200, 400, 403, 404, 429 or 500.
X-RateLimit-Limit calls per hour on this key
X-RateLimit-Remaining calls left this hour
X-RateLimit-Reset unix seconds when the hour resets
X-Quota-Limit monthly allowance (absent when uncapped)
X-Quota-Remaining calls left this month (absent when uncapped)curl -s -D - -o /dev/null "https://opportunityplatform.co.uk/api/v1/jobs?limit=1" \
-H "Authorization: Bearer $OP_API_KEY" | grep -i '^x-'When you hit a limit
Retry-After: 1260
{
"error": {
"code": "rate_limited",
"message": "This key allows 100 requests per hour.",
"request_id": "req_3f9c1a2b4d5e6f708192a3b4c5d6e7f8",
"retry_after_seconds": 1260
}
}error.code says which ceiling you reached: rate_limited for the hour, quota_exceeded for the month. Retry-After points at the right boundary, so after a monthly rejection it is the start of next month, not a few minutes away.
| You see | Do this |
|---|---|
| 429, hourly | Wait Retry-After seconds, then resume. Spread calls across the hour. |
| 429, monthly | Stop until the 1st, or talk to us about your plan. Retrying sooner will be refused. |
| X-RateLimit-Remaining near 0 | Slow down before you are refused. |
Good habits
- Cache job lists for a few minutes. New jobs do not appear by the second.
- Use webhooks for things that happen, rather than polling for them.
- Back off exponentially on 5xx responses. Those do not count as a rate limit.
What is counted
Every call to a key-authenticated endpoint counts, including /v1/compliance-export, calls to /v1/webhooks/endpoints made with a key, and calls that end in an error, because the call was still made.