Idempotenz

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.

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.
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`. Nutze einen neuen Key.
Denselben Key, während die erste Anfrage noch läuft	409 `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:

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.

#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`, 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`.
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.