> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esheria.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits And Timeouts

> Design clients that handle local rate limits, timeouts, retries, and idempotent replay safely.

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:

1. An IP-level pre-authentication abuse limit (3,000 requests/minute by default).
2. 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:

```bash theme={null}
export ESHERIA_TIMEOUT_SECONDS="30"
export ESHERIA_RETRY_COUNT="2"
```

You can override per command:

```bash theme={null}
esheria --timeout 8 --retry-count 0 packs list --format json
```

## Pagination

List endpoints use `limit` and `offset`.

```bash theme={null}
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.