Rate Limiting
What the tiers are, what headers to expect, and how to handle 429 responses.
Endpoint schemas and parameter details live in the API Reference. This page
covers rate limiting behavior — what the tiers are, what headers to expect, and how to handle
429 responses.
Behavior
The API enforces hard rate limits. When you exceed the limit, the server immediately returns 429 Too Many Requests with an RFC 7807 Problem Details body. There is no soft throttling or request queuing — your request is rejected outright.
Response Headers
Every response (not just 429) includes rate limit headers so you can monitor your usage proactively:
| Header | Type | Description |
|---|---|---|
X-RateLimit-Limit | integer | Maximum requests allowed in the current window |
X-RateLimit-Remaining | integer | Requests remaining in the current window |
X-RateLimit-Reset | integer | Unix timestamp (seconds) when the window resets |
Retry-After | integer | Only on 429 responses. Seconds until you can retry. |
Example 429 response:
{
"type": "https://api.kyndex.co/errors/RATE_LIMITED",
"title": "Too Many Requests",
"status": 429,
"code": "RATE_LIMITED",
"limit": 10,
"window": 60,
"reset_at": "2026-01-15T10:30:45.000Z"
}limit is the request budget for the window, window is the window length in seconds, and reset_at is the ISO 8601 timestamp when the window resets. Use Retry-After rather than reset_at for retry timing — it accounts for the time already elapsed.
Rate Limit Tiers
Different endpoint categories have different budgets. All windows use a sliding counter.
| Category | Limit | Window | Applies to |
|---|---|---|---|
auth | 10 req | 1 min | All /auth/* endpoints |
documents_write | 100 req | 1 hr | Document create, reservations |
documents_read | 1,000 req | 1 hr | Document list, content, OCR, search |
grants_write | 50 req | 1 hr | Grant create, lifecycle transitions |
grants_read | 500 req | 1 hr | Grant list, discovery |
default | 100 req | 1 min | Entities, jobs, deliveries, and all others |
Auth endpoints have a stricter threshold than all other categories. Login and registration flows are the primary target for credential stuffing and brute-force attacks.
OPAQUE Endpoints: Per-Account Limit
POST /auth/opaque/authenticate-start, authenticate-finish, register-start, register-finish, and POST /auth/challenges carry an additional per-account rate limit on top of the standard auth tier. The per-account check uses the blind login index from the request body — the server enforces the limit without learning the user's identity.
Both the IP check and the per-account check must pass. If either is exhausted, the request returns 429.
Recommended Client Behavior
- Monitor headers proactively — check
X-RateLimit-Remainingbefore hitting zero - Respect
Retry-After— wait the full duration before retrying - Use exponential backoff — if you receive multiple
429s in succession, increase your wait time geometrically - Don't retry immediately — the
429is a hard rejection, not a suggestion