# Idempotency from the start

After this guide, a retry after a network drop no longer creates a second operation: your client sends an `Idempotency-Key` with every write call, and the platform returns the stored response on a retry instead of a new resource.

> **Type:** guide
> **For:** Developers whose integration creates or changes resources
> **Prerequisite:** a key `ak_…` with a write permission, in the example `asset.folder.create` (class **Media automation**)
> **Where:** command line

## Steps

1. Generate a key for each operation, at least 8 characters long, ideally one that your system knows anyway, such as an order or import number. It only has to be unique within your organization for this method and this path.

   ```bash
   export IDEM="import-2026-09-08-0042"
   ```

2. Send the key as the header `Idempotency-Key` with the write call:

   ```bash
   curl -sSi "$SZENERA_API/v1/folders" \
     -H "Authorization: Bearer $SZENERA_API_KEY" \
     -H "Idempotency-Key: $IDEM" \
     -H "Content-Type: application/json" \
     -d '{"name":"Videos"}'
   ```

   ```json
   {
     "id": "fld_01KKEQQF80MAPPE00000000003",
     "name": "Videos",
     "kind": "regular",
     "path": "/Videos",
     "parentFolderId": null,
     "depth": 0,
     "createdAt": "2026-03-11T15:20:00.000Z"
   }
   ```

   The platform stores the status, the body, and the headers `ETag`, `Location`, and `X-Trace-Id` of this first response for 24 hours.

3. If the connection drops before the response reaches you, repeat the same call with the same key and the same body. No second folder is created.

4. Recognize the retry by the header `Idempotent-Replay: true`: you received the stored response, and the action did not run again.

   ```http
   HTTP/1.1 201 Created
   Idempotent-Replay: true
   ```

## Rules that apply

- The cache is separate per organization, method, and path. The same key on a different path or with a different method hits a different entry.
- Shorter than 8 characters: `422 Validation.Failed`.
- The same key with a different body is not a retry but a second operation under a borrowed name: `422 Validation.IdempotencyKeyReused`. Neither the old response nor a new operation comes back.
- If a route enforces the key and it is missing: `409 Validation.IdempotencyKeyRequired`.
- After 24 hours the entry has expired. The same key then runs the operation again.
- For changes to versioned resources (scenes, playlists, programs, roles, displays), `If-Match` with the `version` you read from the body is added. The idempotency key protects against double execution, and `If-Match` protects against overwriting other people’s changes. See [Concurrent changes: ETag and If-Match](/api/etag-and-if-match).

## Through the command line

`szenera api post` and the other write commands generate a fresh key for every call when you give none. Only to continue an aborted retry do you set it yourself:

```bash
szenera api post /v1/folders '{"name":"Videos"}' --idempotency-key="$IDEM"
```

## Check the result

- The second call returns the same status and the same body as the first, with the same ID `fld_…`, and additionally `Idempotent-Replay: true`.
- The folder list contains the folder exactly once.

## If something goes wrong

| Symptom | Meaning | Solution |
|---|---|---|
| The second call does create a second resource | A different path, a different method, a different key, or the entry expired after 24 hours. | Compare the key, path, and method of the retry with the first attempt. Finish retries within 24 hours. |
| `422 Validation.Failed` with “Idempotency-Key too short” | The key has fewer than 8 characters. | Choose a longer key. |
| `422 Validation.IdempotencyKeyReused` | The same key with a different body. | For a new operation, issue a new key. |
| `409 Validation.IdempotencyKeyRequired` | The route requires the key. | Always send the header. |

## Related

- [Concurrent changes: ETag and If-Match](/api/etag-and-if-match)
- [The error format](/api/error-format)
- [Scripts and CI](/cli/scripts-and-ci)