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

# Idempotency key required (IDEMPOTENCY_REQUIRED)

> A mutating tool was called without an idempotency_key; Aeris refuses to run it.

## What it means

Every mutating tool on the Aeris MCP surface requires an `idempotency_key` so a network retry never accidentally applies the same change twice. If the key is absent, the request is rejected before any state change happens.

## How to fix

* Mint a client-side key (UUIDv4 or any stable per-intent string) and pass it with the call.
* Reuse the same key when retrying a call whose outcome is unknown — Aeris will return the original result rather than repeat the action.
* Mint a **fresh** key for each new intent, not once per session.

## Response envelope

```json theme={"dark"}
{
  "ok": false,
  "error_envelope": {
    "code": "IDEMPOTENCY_REQUIRED",
    "message": "This mutating tool requires an idempotency_key.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/idempotency-required",
    "retryable": false,
    "retry_after_ms": null,
    "details": {
      "tool": "propose_pause_wasted"
    }
  }
}
```

## Related

* [`IDEMPOTENCY_CONFLICT`](/mcp/errors/idempotency-conflict) — the key was provided but reused with a different payload.
* [`INVALID_INPUT`](/mcp/errors/invalid-input) — the other 422 shape.