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 a Problem Details response body. There is no soft throttling or request queuing — your request is rejected outright.
Response Headers
Every response from a rate-limited endpoint (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.literal.so/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 are fixed — counts reset at the window boundary, not on a sliding interval.
| 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: Login-Bucket Limit
OPAQUE registration, login, and challenge endpoints carry an additional login-bucket limit on top of the standard auth tier. The check uses the blind login index from the request body, so Literal can rate-limit repeated attempts for the same bucket without receiving the raw email address.
Both the IP check and the login-bucket 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
See Also
- Error Handling — complete error code reference with status meanings
- Session Lifecycle — how session expiry produces
401vs. rate-limit429
Last updated on