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

# Idempotency

> Prevent duplicate sandboxes when a create request is retried.

`POST /api/sessions` requires an `Idempotency-Key` header no longer than 200
characters.

```http theme={null}
Idempotency-Key: ci-12345-attempt-1-shard-3-github
```

* reuse a key only with the exact same create body
* a different body with the same key returns `409`
* while the idempotency record is retained, a retry of the same body returns the original create result
* provider mutation idempotency remains a separate concern

For CI, derive the key from the provider run ID, attempt, job, matrix values,
shard, logical test group, and a digest of the exact create body. Hash long
identity fields instead of truncating away the part that makes jobs unique.

The create key prevents duplicate Archal sandboxes. It does not make GitHub,
Slack, Stripe, or another provider write idempotent.