> For the complete documentation index, see [llms.txt](https://shinkalabs.gitbook.io/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shinkalabs.gitbook.io/hub/andromeda/guides/idempotency.md).

# Idempotency keys

Every mutating endpoint accepts an `Idempotency-Key` header. With it, a retried request replays the original response byte for byte instead of executing again. Use it on anything that creates a side effect: DKG, signing, submits, recovery contributions, policy changes, future-sign arming.

## How to use it

Generate a unique value per logical operation (a UUID is fine) and send it on the request and on any retry of that same operation:

```bash
KEY=$(uuidgen)

curl -X POST https://api.andromedainfra.pro/v1/dwallet/sign/submit \
  -H "X-Api-Key: $ANDROMEDA_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "dwalletAddress": "<DWALLET>", "messageHashHex": "<HASH>" }'
```

If the call times out or the connection drops, retry with the **same** `KEY` and the **same** body. You get the original outcome, and the operation runs at most once.

## The rules

* **Same key, same body, returns the cached response.** No re-execution. This includes MCP tool calls.
* **Same key, different body, fails with `422`.** This is a guard against accidentally reusing a key for a different operation. If you genuinely have a new operation, use a new key.
* **Scoped per API key.** Two different keys using the same `Idempotency-Key` value do not collide.
* **Cached for a window, not forever.** Replays work for a bounded time after the first call; after that the key is forgotten and a request with it executes normally.

## Where it matters most

* **DKG.** A retry without an idempotency key could start a second key generation.
* **Signing.** A retry could consume a second presignature.
* **Recovery contributions.** A retry could double-record a member's contribution.
* **Policy changes.** A retry could apply a change twice.

## Replays are audited

When a request is served from the idempotency cache rather than executed, that replay is recorded in the tenant's [audit log](/hub/andromeda/guides/audit-log.md). It is one of the canonical event types.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shinkalabs.gitbook.io/hub/andromeda/guides/idempotency.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.