Idempotency keys.

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

A create with an idempotency key

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 for the retry recipe.

Get started

Agents

API reference

Guides

Reference

Idempotency keys.

When to use it

How it works

What it does not cover

​When to use it

​How it works

​What it does not cover

When to use it

How it works

What it does not cover