Rate limits

The OikoHire API enforces sliding-window rate limits tracked per API key using Redis. Limits are separate for standard endpoints (read/list) and AI endpoints (match, score).

---

Limits by plan

Plan tier	Standard (per 60 s)	AI (per 24 h)
Starter / default	60 requests	100 calls
Pro / Growth	300 requests	500 calls
Agency / Enterprise	1,000 requests	2,500 calls

• /external/candidates and /external/jobs/:id count towards the standard window.
• /external/ai/match-jobs and /external/ai/score-interview count towards the AI daily window.

Per-plan overrides

Enterprise plans can negotiate a custom aiCallLimit that overrides the table defaults above.

---

Rate limit response headers

Every authenticated response includes the following headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests still available in the current window
X-RateLimit-Reset	Unix timestamp (seconds) when the window resets

When a limit is exceeded, the API also adds:

Header	Description
Retry-After	Seconds to wait before retrying

---

Rate limited response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720612800
Retry-After: 14
Content-Type: application/json

{
  "statusCode": 429,
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Try again in 14 seconds.",
  "retryAfter": 14
}

---

Best practices

• Respect Retry-After: Use the Retry-After header value to schedule your retry rather than hammering the API.
• Use async mode for AI calls: For match-jobs and score-interview, pass "async": true to dispatch the job immediately and poll for the result. This avoids holding open a long HTTP connection and makes better use of your AI quota.
• Cache search results: The candidate pool does not change instantly — caching GET /external/candidates results for 60–300 seconds significantly reduces your standard call count.
• Upgrade your plan if you regularly hit AI limits in production workloads.