> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideren.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency keys.

> Send an Idempotency-Key when creating a batch, and a retried request is answered from the first attempt instead of running the work twice.

## When to use it

Networks drop connections. When a client can't tell whether a request reached Sideren, it
retries — and without an idempotency key, that retry runs the work (and bills it) a second
time. Send an `Idempotency-Key` header and Sideren recognises the retry.

Idempotency applies to batch creation, where a duplicate does real work:
`POST /v1/messages/batches` and `POST /v1/batches` ([Batches](/api/batches)).

```sh title="A create with an idempotency key" theme={null}
curl https://api.sideren.io/v1/messages/batches \
  -H "x-api-key: $SIDEREN_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: 7c1f0d2e-8b1a-4f55-9b2e-0f6a1d3c9e41" \
  -d '{"requests":[...]}'
```

Use a fresh random value (a UUID) per logical request, and reuse it only when retrying that
same request. Keys up to 200 characters are accepted.

## How it works

A key is remembered for **24 hours**, scoped to your account and the collection you are
creating in.

| You send | You get |
| - | - |
| The same key and the same body (batches) | The original response, replayed with `200` and an `idempotency-replayed: true` header. |
| The same key with a **different** body (batches) | `409` `idempotency_conflict` — a key belongs to one request body; use a new key for a new request. |
| The same key while the create is still in flight (batches) | `409` `batch_creation_in_progress` — wait, then retry the same key. |

## What it does not cover

An idempotency key protects the **create call**. It can't undo side effects your own client
caused — for example tools your agent already ran after reading a streamed tool call.
Guard those in your own code. The chat endpoints have no idempotency mechanism: a retried
chat request is a new request.

See [Errors](/errors) for the retry recipe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.