Rate Limits

Summary

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.

Capabilities

Current Limits

GET, HEAD, and OPTIONS count as reads. POST, PUT, PATCH, DELETE, and other methods count as writes.

These limits describe the standard public REST middleware. OAuth also has its separate limit. Plan usage allowances do not replace these per-minute limits, and specialized routes can use different middleware.

Keys belonging to the same user share authenticated buckets for the same authentication type and endpoint group, even across teams. Many services behind one public IP also share the pre-authentication allowance. A new key does not create a new user allowance. MCP uses HTTP POST for protocol requests, so a read-only tool call can consume the HTTP write allowance.

Prerequisites

Integrators need an authenticated identity, an understanding of different HTTP method classes, and may require an API key or OAuth credentials, depending on which routes are being accessed.

Concepts

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 a user identity, service principal, or public IP, including workers with separate keys.
• 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. Every attempt still passes the pre-authentication limiter. A cached replay returns before the authenticated limiter, so its stored rate-limit headers can describe the original response rather than current remaining capacity.

Replay caches successful 2xx responses for 24 hours; it does not compare bodies or cache failures. Reusing a key with changed content can return the old result. Adding a key after an uncertain unkeyed write cannot protect the earlier attempt.

Workflow

Backoff

1. Stop requests in the affected endpoint group.
2. Wait for the Retry-After value.
3. Add jitter before you resume the concurrent workers.
4. Reduce concurrency.
5. Retry the same read, or a write whose rate-limit response shows it was refused before execution. For an uncertain write outcome, reconcile the resource first.

Do not treat a network failure or server error as proof that a write did nothing, even with an Idempotency-Key. Check persisted state before repeating it. If the rate-limit service itself fails, the response can be a server error rather than 429; use bounded error handling instead of bypassing the limit.

Behavior specification

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. The same header names are used by multiple limiters, so a response does not report every bucket. Retry-After is an integer number of seconds, rounded up with a minimum of one second.

Diagrams

Screenshots

Not applicable: this page describes an API or a non-visual workflow rather than an application screen.

Verification

Use an isolated local fixture; do not exhaust a shared or production quota.

1. Exercise an authenticated read bucket to its limit and check 429, Retry-After, and remaining zero. Check write and OAuth buckets separately.
2. Confirm two keys for the same user share the relevant bucket, while unrelated endpoint groups can have independent counters.
3. Check successful response headers, then replay an exact successful keyed write. Confirm a cached result does not imply fresh authenticated rate-limit headers.
4. Simulate an uncertain unkeyed write and confirm the client checks persistence. Adding an idempotency key afterward must not be treated as duplicate prevention.
5. Simulate unavailable rate-limit storage and verify a visible failure with bounded client retries.

Related

Related Pages

• Errors
• Pagination
• Authentication