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

# Rate limited (RATE_LIMITED)

> Per-user or per-org request budget exceeded; retry after the advertised delay.

## What it means

Aeris enforces per-user and per-organisation QPS ceilings so a runaway agent loop cannot drain your budget or degrade other tenants. When the ceiling is hit the request is rejected with a mandatory `retry_after_ms` hint the client MUST honour.

This is the only 4xx that is safely retryable — no state changed.

## How to fix

* Sleep for at least `retry_after_ms` before retrying the exact same call.
* If your workflow batches actions, batch them further so each request does more work.
* If you see this consistently on read tools, cache results client-side and de-duplicate identical requests within a short window.

<Warning>
  The MCP Worker mirrors this into a JSON-RPC error with the same `retry_after_ms`. Do not busy-loop — ignoring the hint will only extend the throttle window.
</Warning>

## Response envelope

```json theme={"dark"}
{
  "ok": false,
  "error_envelope": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/rate-limited",
    "retryable": true,
    "retry_after_ms": 2500,
    "details": {}
  }
}
```

## Related

* [`UPSTREAM_UNAVAILABLE`](/mcp/errors/upstream-unavailable) — the other retryable, but caused by a partner outage.
* [`TIMEOUT`](/mcp/errors/timeout) — the tool ran but did not finish inside its budget.