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

# Tool call timed out (TIMEOUT)

> The tool ran but did not finish inside its declared timeout budget.

## What it means

Every tool declares a `timeoutMs` in its `ToolSpec`. If a call exceeds it, Aeris aborts and returns `TIMEOUT`. This is different from `UPSTREAM_UNAVAILABLE`: the upstream may have been perfectly healthy, but our call to it took too long — usually because the request scope is too broad.

Retryable, but only if you also narrow the request.

## How to fix

* Reduce the scope: shorter date range, fewer entities, smaller page size.
* Wait `retry_after_ms` (default 2000ms) before retrying the same call.
* For write actions, reuse the original `idempotency_key` — a duplicate write is impossible even if the first attempt actually landed.

## Response envelope

```json theme={"dark"}
{
  "ok": false,
  "error_envelope": {
    "code": "TIMEOUT",
    "message": "The tool call timed out.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/timeout",
    "retryable": true,
    "retry_after_ms": 2000,
    "details": {
      "timeout_ms": 30000
    }
  }
}
```

`details.timeout_ms` is the ceiling the tool was configured for — useful for right-sizing your retries.

## Related

* [`UPSTREAM_UNAVAILABLE`](/mcp/errors/upstream-unavailable) — upstream itself was down.
* [`RATE_LIMITED`](/mcp/errors/rate-limited) — the other 4xx that's retryable.