# Idempotenz von Anfang an

Nach dieser Anleitung erzeugt eine Wiederholung nach Netzabbruch keinen zweiten Vorgang mehr: Ihr Client schickt zu jedem verändernden Aufruf einen `Idempotency-Key`, und die Plattform liefert bei einer Wiederholung die gespeicherte Antwort statt einer neuen Ressource.

> **Typ:** anleitung
> **Für wen:** Entwicklerinnen und Entwickler, deren Anbindung Ressourcen anlegt oder ändert
> **Voraussetzung:** ein Schlüssel `ak_…` mit einem schreibenden Recht — im Beispiel `asset.folder.create` (Klasse **Medien-Automation**)
> **Ort:** Kommandozeile

## Schritte

1. Erzeugen Sie je Vorgang einen Schlüssel von mindestens 8 Zeichen — am besten einen, den Ihr System ohnehin kennt, etwa eine Auftrags- oder Importnummer. Er muss nur innerhalb Ihrer Organisation für diese Methode und diesen Pfad eindeutig sein.

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

2. Senden Sie den Schlüssel als Kopfzeile `Idempotency-Key` mit dem verändernden Aufruf:

   ```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"
   }
   ```

   Die Plattform speichert Status, Rumpf und die Kopfzeilen `ETag`, `Location` und `X-Trace-Id` dieser ersten Antwort für 24 Stunden.

3. Bricht die Verbindung ab, bevor die Antwort bei Ihnen ankommt, wiederholen Sie denselben Aufruf mit demselben Schlüssel und demselben Rumpf. Es entsteht kein zweiter Ordner.

4. Erkennen Sie die Wiederholung an der Kopfzeile `Idempotent-Replay: true`: Sie bekamen die gespeicherte Antwort, die Aktion lief nicht erneut.

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

## Regeln, die dabei gelten

- Der Zwischenspeicher ist getrennt je Organisation, Methode und Pfad. Derselbe Schlüssel auf einem anderen Pfad oder mit einer anderen Methode trifft einen anderen Eintrag.
- Kürzer als 8 Zeichen: `422 Validation.Failed`.
- Derselbe Schlüssel mit einem anderen Rumpf ist keine Wiederholung, sondern ein zweiter Vorgang unter geborgtem Namen: `422 Validation.IdempotencyKeyReused`. Weder die alte Antwort noch ein neuer Vorgang kommt zurück.
- Auf Routen, die den Schlüssel erzwingen, fehlt er: `409 Validation.IdempotencyKeyRequired`.
- Nach 24 Stunden ist der Eintrag verfallen; derselbe Schlüssel führt den Vorgang dann erneut aus.
- Für Änderungen an versionierten Ressourcen (Szenen, Playlisten, Programme, Rollen, Displays) kommt `If-Match` mit der gelesenen `version` aus dem Rumpf hinzu — der Idempotency-Key schützt vor der doppelten Ausführung, `If-Match` vor dem Überschreiben fremder Änderungen. Siehe [ETag und If-Match](/de/api/etag-and-if-match).

## Über die Kommandozeile

`szenera api post` und die übrigen schreibenden Befehle erzeugen ohne Angabe je Aufruf einen frischen Schlüssel. Nur zum Fortsetzen einer abgebrochenen Wiederholung setzen Sie ihn selbst:

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

## Ergebnis prüfen

- Der zweite Aufruf liefert denselben Status und denselben Rumpf wie der erste — dieselbe Kennung `fld_…` — und zusätzlich `Idempotent-Replay: true`.
- Die Ordnerliste enthält den Ordner genau einmal.

## Wenn etwas nicht klappt

| Symptom | Bedeutung | Lösung |
|---|---|---|
| Der zweite Aufruf legt doch eine zweite Ressource an | Anderer Pfad, andere Methode, anderer Schlüssel — oder der Eintrag ist nach 24 Stunden verfallen. | Schlüssel, Pfad und Methode der Wiederholung mit dem ersten Versuch vergleichen; Wiederholungen innerhalb von 24 Stunden abschließen. |
| `422 Validation.Failed` mit „Idempotency-Key too short“ | Der Schlüssel hat weniger als 8 Zeichen. | Längeren Schlüssel wählen. |
| `422 Validation.IdempotencyKeyReused` | Derselbe Schlüssel mit einem anderen Rumpf. | Für einen neuen Vorgang einen neuen Schlüssel vergeben. |
| `409 Validation.IdempotencyKeyRequired` | Die Route verlangt den Schlüssel. | Kopfzeile immer mitsenden. |

## Weiterführendes

- [ETag und If-Match](/de/api/etag-and-if-match)
- [Fehlerformat](/de/api/error-format)
- [Skripte und CI](/de/cli/scripts-and-ci)