> Keiro Labs API documentation - Idempotency
> Page: https://docs.keirolabs.ai/idempotency.html
> Markdown: https://docs.keirolabs.ai/idempotency.md
> Agent index: https://docs.keirolabs.ai/llms.txt
> API base URL: https://api.keirolabs.ai/v1
> Auth: send "Authorization: Bearer <api-key>" with a key created in the
> Keiro console (https://console.keirolabs.ai/api-keys). Use credentials saved by
> `keiro setup`, or resolve the key from a secret manager or an owner-only
> secret file and pass it to the client explicitly. Never read another
> provider's variable, and never put raw key material in environment
> variables, code, docs, or logs.

# Idempotency

Send an idempotency key with retry-sensitive requests so a safely retried
request runs at most once. When a key is reused, Keiro replays the original
response instead of executing the request again.

## When to use idempotency keys

Use an idempotency key when a network error, timeout, or client retry could
resend a request you do not want to run twice. Generate a unique key for each
logical operation, reuse the same key when you retry that operation, and use a
new key for a new operation.

## Send an idempotency key

Set the `Idempotency-Key` request header on the request. With the
OpenAI-compatible SDKs, pass it as a per-request custom header. You may also send
an `idempotency_key` field in the JSON body. If you send both, they must be
equal, or the request is rejected with `400`.

A key is any non-empty string with no leading or trailing whitespace. Use a
value that is unique per operation, such as a UUID. Keys are scoped to your
organization, so the same key value used by a different organization never
collides with yours.

## Replay behavior

The first request to complete with a given key stores its response for replay. A
later request that reuses the key with the same endpoint and request body
receives the stored response instead of running again.

| Response header | Meaning |
|---|---|
| `X-Idempotent-Replay: true` | The response is a replay of an earlier request, not a new run |
| `X-Original-Request-Id` | The request id of the original request that produced the stored response |

A replay returns the original status code and body. Retry-sensitive side
effects, including usage billing, happen once for the original request.

## Conflicts

If you reuse a key with a different endpoint or a different request body, Keiro
returns `409` with `code` `idempotency_key_conflict` and an
`X-Original-Request-Id` header pointing to the original request. Use a new key
when the request is genuinely different, or resend the exact original request to
get a replay.

## Retention

Stored keys and replays are short-lived operational state. A key is replayable
for up to 24 hours after it first completes. After it expires, the same key
value starts a new operation. See [Data retention](data-retention.md) for the
retention posture.

## Example

```bash
printf 'Keiro API key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS https://api.keirolabs.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f3b8c9a-2d1e-4a7b-9c0f-6e2a1b4d7c88" \
  -d '{
    "model": "eb1-preview",
    "input": "Summarize the incident report."
  }' \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER"
```

Resend the same command with the same `Idempotency-Key` to receive the original
response with `X-Idempotent-Replay: true`.

## Compatibility notes

- Idempotency applies to `POST` requests on the completion endpoints,
  `/v1/chat/completions`, `/v1/responses`, and `/v1/messages`.
- Treat `409 idempotency_key_conflict` as a client error; do not retry it
  without changing the key or the request. See [Errors](errors.md).

## Related pages

- [Errors](errors.md)
- [Streaming](streaming.md)
- [Data retention](data-retention.md)