Skip to main content

​
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.
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.

​
Response envelope

{
  "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": {}
  }
}
  • UPSTREAM_UNAVAILABLE — the other retryable, but caused by a partner outage.
  • TIMEOUT — the tool ran but did not finish inside its budget.