# Idempotency

State-changing endpoints require `Idempotency-Key`.

Use idempotency to make retries safe when the network fails, the client times out, or the server writes state before the response reaches you.

## Header

```http
Idempotency-Key: order_1001_create_payment
```

Keys must be 8 to 128 visible ASCII characters.

## Retention

Production idempotency keys are retained for 24 hours.

The current mock stores keys in memory until the mock process restarts. A restart can clear mock idempotency history before 24 hours.

## Same Key, Same Body

If you retry with the same idempotency key and the same request body, Artum returns the original created resource response.

Use this for safe client retries.

## Same Key, Different Body

If you reuse an idempotency key with a different request body, Artum returns `409 Conflict`.

```json
{
  "error": {
    "code": "idempotency_key_reused_with_different_payload",
    "message": "Idempotency-Key was already used with a different request body"
  }
}
```

## Recommended Key Shape

Use a stable key per business operation:

```
order_1001_create_payment
webhook_endpoint_primary_create
```

Do not generate a new random key for retries of the same operation.


---

# Agent Instructions: 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://docs.artum.app/payments/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.