Rate Limits
Plan Eigenn API traffic around authenticated, pre-authentication, and OAuth request limits.
Eigenn applies more than one rate-limit layer. A protected request passes an IP-based pre-authentication limit before it reaches the authenticated identity limit.
Current Limits
| Request class | Limit | Window | Key |
|---|---|---|---|
| Authenticated reads | 300 | 60 seconds | Authenticated identity, method class, and endpoint group |
| Authenticated writes | 30 | 60 seconds | Authenticated identity, method class, and endpoint group |
| Pre-authentication reads | 1,000 | 60 seconds | Client IP, method class, and endpoint group |
| Pre-authentication writes | 120 | 60 seconds | Client IP, method class, and endpoint group |
| OAuth endpoints | 10 | 15 minutes | Client IP, method, and OAuth endpoint |
GET, HEAD, and OPTIONS count as reads. POST, PUT, PATCH, DELETE, and other methods count as writes.
The authenticated limit is normally the smaller resource limit, but many services behind one public IP can also consume the shared pre-authentication allowance.
Response Headers
Successful limited requests can include:
- X-RateLimit-Limit
- X-RateLimit-Remaining
A rate-limited response includes:
- Retry-After
- X-RateLimit-Limit
- X-RateLimit-Remaining: 0
The response body can be minimal:
{
"error": "Read rate limit exceeded"
}Do not require every optional standard error field to be present on a 429.
Backoff
- Stop requests in the affected endpoint group.
- Wait for the Retry-After value.
- Add jitter before resuming concurrent workers.
- Reduce concurrency.
- Retry the same read or the same idempotent write.
Do not retry a non-idempotent write automatically unless you supplied a stable Idempotency-Key and can safely interpret the prior response.
Shape Integration Traffic
- Cache reads that do not need live data.
- Use cursor pagination instead of polling the first page.
- Keep exports bounded by date and stable filters.
- Coordinate workers that share one API key or public IP.
- Use bulk transaction operations where they match the business action.
- Avoid testing OAuth credentials in a tight loop; its limit is intentionally lower.
Endpoint Groups
Limits are grouped by normalized endpoint path, not only by the entire API key. Requests to different resource groups can have independent authenticated counters, while repeated requests to IDs under the same group share a bucket.
Do not depend on the internal grouping shape as a way to bypass limits. Treat the documented values as operating ceilings.
Rate Limits and Idempotency
An authenticated write with an idempotency key can be:
- processed and marked created
- returned from the replay cache
- returned after waiting for the first request
- rejected with 409 while the first request is still processing
- rejected with 503 when the replay guard is unavailable
Respect Retry-After for the latter two cases. A replay does not provide permission to reuse the same key for a different operation.