Rate Limits And Timeouts

The API is designed for deterministic, source-backed workflows. Client code should use bounded timeouts, conservative retries, and idempotency keys on mutating requests.

Recommended Client Defaults

Setting	Recommended value
Request timeout	`30` seconds
Retry count	`2` for transient network failures
Retry methods	Safe `GET` requests and idempotent `POST` retries with the same idempotency key
Page size	Start with `limit=25`; increase only when needed

Production Rate Limits

Esheria applies two independent controls:

An IP-level pre-authentication abuse limit (3,000 requests/minute by default).
An authenticated workspace limit from the active plan, shared by all API and OAuth tokens in that workspace.

Plan	Authenticated requests/minute
Sandbox	30
Developer	60
Team	180
Business	600
Enterprise / Embedded	1,200+ contracted

Production readiness requires the shared Redis limiter through API_REDIS_URL. Customers behind the same NAT share only the high pre-auth IP guard; after authentication, their paid limit is isolated by workspace. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After when blocked. The CLI uses:

export ESHERIA_TIMEOUT_SECONDS="30"
export ESHERIA_RETRY_COUNT="2"

You can override per command:

esheria --timeout 8 --retry-count 0 packs list --format json

Pagination

List endpoints use limit and offset.

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/SG-MAS-TRM-OUTSOURCING/obligations?limit=25&offset=0" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

Failure Modes

Symptom	Meaning	Action
HTTP timeout	Runtime, network, or reverse-proxy issue	Retry with bounded attempts and store the failed `trace_id` if present
`429` or rate-limit response	Pre-auth abuse limit or authenticated plan limit was exceeded	Honor `Retry-After`, back off, and reduce concurrency
`409 idempotency_key_conflict`	Same key reused with different payload	Generate a new idempotency key
Large responses are slow	Full export or broad query	Use filters and pagination before exporting a whole pack

Production Notes

If Redis is unavailable, readiness fails and production billing rate checks fail closed. Restore Redis before accepting customer traffic; development may still use the bounded in-process limiter.

​Recommended Client Defaults

​Production Rate Limits

​Pagination

​Failure Modes

​Production Notes

Recommended Client Defaults

Production Rate Limits

Pagination

Failure Modes

Production Notes