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 expect every optional standard error field on a 429.
Backoff
- Stop requests in the affected endpoint group.
- Wait for the Retry-After value.
- Add jitter before you resume the 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 repeated requests to 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.
- Do not test OAuth credentials in a tight loop. The OAuth limit is lower by design.
Endpoint Groups
Eigenn groups limits by normalized endpoint path, not only by the entire API key. Requests to different resource groups can have independent authenticated counters. Repeated requests to IDs under the same group share a bucket.
Do not depend on the internal group shape as a way to bypass limits. Treat the documented values as the operational 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 a wait for the first request
- rejected with 409 while the first request is still in progress
- rejected with 503 when the replay guard is unavailable
Respect Retry-After for the latter two cases. A replay does not give permission to reuse the same key for a different operation.