# Idempotenz

> Wie du einen Aufruf, der Nachrichten sendet, wiederholst, ohne doppelt zu senden. Der Header Idempotency-Key, wie lange er gespeichert bleibt und was bei einer Wiederholung passiert.

Stand: 2026-10-30. Quelle: https://docs.smartchat.marketing/de/concepts/idempotency/

Ein Netz kann ausfallen, nachdem der Server die Arbeit getan hat, aber bevor du die Antwort siehst. Sendest du die Anfrage dann einfach noch einmal, kann eine Nachricht doppelt gesendet werden. Der Header `Idempotency-Key` verhindert das.

## So nutzt du ihn

Sende für jede **Operation** einen eindeutigen Wert, zum Beispiel eine UUID. Nutze denselben Wert, wenn du diese Operation wiederholst. Dieses Beispiel legt einen Kontakt an; Aufrufe, die Nachrichten senden, nutzen den Header genauso.

```bash run
curl -X POST "https://api.smartchat.marketing/v1/contacts" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mia Muster", "phone": "+4915112345678"}'
```

- Der Key hat 1 bis 255 sichtbare ASCII-Zeichen.
- Er ist **Pflicht** bei jedem Aufruf, der Nachrichten sendet, und bei jedem Aufruf, der etwas mit Wirkung nach außen anlegt. Die Referenzseite eines Aufrufs sagt "Pflicht". Ohne ihn lautet die Antwort [`idempotency_key_required`](https://docs.smartchat.marketing/de/errors/#idempotency_key_required).
- Bei einigen anderen Aufrufen ist er freiwillig und funktioniert, wenn du ihn sendest.

## Was bei einer Wiederholung passiert

| Du sendest | Du bekommst |
|---|---|
| Denselben Key und dieselbe Anfrage | Die erste Antwort noch einmal, mit dem Header `Idempotent-Replayed: true`. Nichts wird doppelt getan. |
| Denselben Key und eine andere Anfrage | 422 [`idempotency_key_reused`](https://docs.smartchat.marketing/de/errors/#idempotency_key_reused). Nutze einen neuen Key. |
| Denselben Key, während die erste Anfrage noch läuft | 409 [`idempotency_in_progress`](https://docs.smartchat.marketing/de/errors/#idempotency_in_progress) mit `Retry-After`. Warte und wiederhole. |

Keys bleiben 24 Stunden gespeichert. Sie gehören zu deinem Schlüssel und deinem Konto.

## Was nicht gespeichert wird

Antworten mit 401, 403, 409, 429 und 503 werden nicht gespeichert. Es wurde nichts getan oder der Zustand kann sich ändern, deshalb ist der Key wieder frei.

Manche 422-Ablehnungen hängen vom Zustand deines Kontos ab. Es wurde nichts gesendet und der Zustand kann sich ändern (eine Vorlage wird genehmigt, ein Fenster öffnet sich, ein Kontakt bestätigt). Auch diese Ablehnungen werden nicht gespeichert. Du kannst also **dieselbe** Anfrage mit **demselben** Key wiederholen, sobald sich der Zustand geändert hat:

- [`audience_empty`](https://docs.smartchat.marketing/en/errors/#audience_empty)
- [`contact_not_confirmed`](https://docs.smartchat.marketing/en/errors/#contact_not_confirmed)
- [`quota_exceeded`](https://docs.smartchat.marketing/en/errors/#quota_exceeded)
- [`template_not_approved`](https://docs.smartchat.marketing/en/errors/#template_not_approved)
- [`template_rejected`](https://docs.smartchat.marketing/en/errors/#template_rejected)
- [`template_variables_missing`](https://docs.smartchat.marketing/en/errors/#template_variables_missing)
- [`test_phone_not_set`](https://docs.smartchat.marketing/en/errors/#test_phone_not_set)
- [`test_phone_unverified`](https://docs.smartchat.marketing/en/errors/#test_phone_unverified)
- [`whatsapp_not_connected`](https://docs.smartchat.marketing/en/errors/#whatsapp_not_connected)
- [`window_closed`](https://docs.smartchat.marketing/en/errors/#window_closed)

Andere Fehler werden gespeichert, vor allem Fehler von einem Dienst hinter uns (zum Beispiel WhatsApp), weil nicht klar ist, ob die Nachricht gesendet wurde. Eine Wiederholung mit demselben Key gibt dann dieselbe Antwort und nie ein zweites Senden.

## Aufrufe, die absichtlich keinen Key nehmen

`create_webhook_endpoint` und `rotate_webhook_secret` nehmen keinen `Idempotency-Key`. Beide Antworten enthalten ein Signatur-Geheimnis, und ein Geheimnis wird nie im Speicher für Wiederholungen aufbewahrt. Ein wiederholter Aufruf legt deshalb einen zweiten Endpunkt an (das Endpunkt-Limit gilt) oder erneuert das Geheimnis noch einmal. Hast du die Antwort nicht gesehen, liste zuerst deine Endpunkte und melde den überzähligen ab (`unsubscribe_webhook_endpoint`) oder nutze ihn weiter.

> **Wichtig** Endet ein Aufruf mit [`upstream_error`](https://docs.smartchat.marketing/de/errors/#upstream_error), wiederhole die Anfrage nicht mit demselben Key: Du bekämst nur dieselbe Antwort noch einmal. Lies zuerst den Status (bei einem Versand: lies den Versand, [`get_send`](https://docs.smartchat.marketing/en/api/reference/sends/get_send/)). Wurde die Nachricht nicht gesendet, nutze einen **neuen** Key. Wurde sie gesendet, tu nichts.

## Der Key in MCP-Werkzeugen

Die MCP-Werkzeuge nehmen denselben Key als Argument `idempotency_key`. Die Regel ist dieselbe wie bei REST, mit einer Hilfe für Agenten:

| Das Werkzeug | Ohne Key |
|---|---|
| Sendet eine Nachricht | Abgelehnt mit [`idempotency_key_required`](https://docs.smartchat.marketing/de/errors/#idempotency_key_required), wie bei REST. Sende einen Key. |
| Legt etwas an (zum Beispiel einen Kontakt oder einen Entwurf) | Der Server bildet einen Key aus Werkzeugname und Argumenten. Er gilt **eine Minute**. Derselbe Aufruf innerhalb dieser Minute liefert die erste Antwort. Sende deinen eigenen Key, um die vollen 24 Stunden zu bekommen. |
| Ändert etwas, das schon existiert (Status setzen, Tag hinzufügen) | Es wird kein Key gebildet. Eine Wiederholung führt die Änderung noch einmal aus, weil eine Änderung zweimal gewollt sein kann. |

## Pflicht, optional, nicht nötig

Jede Referenzseite zeigt für den `Idempotency-Key` genau eines von drei Wörtern:

| Wort | Bedeutung |
|---|---|
| Required | Ohne den Key antwortet der Aufruf mit [`idempotency_key_required`](https://docs.smartchat.marketing/de/errors/#idempotency_key_required). |
| Optional | Der Aufruf funktioniert auch ohne Key. Sendest du einen Key, liefert eine Wiederholung die erste Antwort. |
| Not needed | Der Aufruf verlangt keinen Key. |

Die Referenzseite sagt in der Zeile "Safe to repeat" außerdem, ob eine Wiederholung von selbst harmlos ist. Das ist ein eigener Fakt. Ein Aufruf, der eine Einstellung ändert oder Daten liest, lässt sich ohne Key wiederholen, weil der Endzustand gleich bleibt. Ein Aufruf, der etwas anlegt oder jedes Mal Arbeit macht, ist ohne Key nicht sicher wiederholbar.