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

# Idempotency

> Safe retries for writes with the Idempotency-Key header

<Info>
  **Quick Summary:** Send a unique `Idempotency-Key` header on any write. Retrying with the same key and the same body replays the original response instead of performing the operation twice.
</Info>

## The contract

```bash theme={null}
curl -X POST "https://prod.skillsdbnext.com/api/v1/careers" \
  -H "Authorization: Bearer sdb_live_YOUR_KEY_HERE" \
  -H "Idempotency-Key: 0e8a7d1c-4f4b-4e9c-a2ce-1b6f2f6f9d55" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maintenance Technician"}'
```

* **First execution** stores the successful response for 24 hours.
* **A retry** (same key, same method, path and body) replays it verbatim, with the header `Idempotency-Replayed: true`, executing nothing.
* **Same key, different content** → 409 [idempotency-key-reused](/api-docs/errors/idempotency-key-reused).
* **Two concurrent duplicates** → exactly one executes; the other briefly waits, then replays or returns a 409 [conflict](/api-docs/errors/conflict) asking you to retry shortly.
* Errors are never replayed — a failed request releases the key so the same key can retry.

## Rules of thumb

Generate a UUID per logical operation. Reuse it only for retries of that exact request. The header is optional — without it every request executes.