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

# Idempotenz

> Wiederhole jeden Schreibvorgang sicher, ohne etwas doppelt anzulegen

## Schreibvorgänge, die eine bestehende Ressource ändern

Es ist kein Header erforderlich. Wo eine Wiederholung früher einen Fehler zurückgab, liefert sie jetzt den aktuellen Zustand:

| Endpunkt | Ein wiederholter Aufruf liefert |
| - | - |
| [Termin stornieren](https://docs.anivahealth.com/de/api/appointments/cancel-appointment.md) | `200` mit dem stornierten Termin |
| [Sendung stornieren](https://docs.anivahealth.com/de/api/shipments/cancel-shipment.md) | `200` mit der stornierten Sendung |
| [Heimtest-Kit-Bestellung stornieren](https://docs.anivahealth.com/de/api/home-kit-orders/cancel-home-kit.md) | `200` mit der stornierten Bestellung |
| [Heimtest-Kit-Bestellung aktivieren](https://docs.anivahealth.com/de/api/home-kit-orders/activate-home-kit.md) | `200`, wenn der Probenahmezeitpunkt derselbe ist |
| Panels oder Biomarker entfernen | `200`, unabhängig davon, ob sie noch zugeordnet waren |

Eine Wiederholung schreibt nichts, und die Antwort enthält `Idempotent-Replayed: true` – an diesem Header unterscheidest du „Ich habe es storniert“ von „es war bereits storniert“.

Drei Ausnahmen liefern stattdessen `409`:

* **Aktivieren mit einem *anderen* `activated_at`.** Der Probenahmezeitpunkt steht im Laborbericht, daher darf ein erneuter Versuch ihn nicht stillschweigend überschreiben.
* **Stornieren eines bereits stornierten Termins mit einem *anderen* `cancellation_reason`.** Derselbe Grund: Der gespeicherte Grund kann inzwischen korrigiert worden sein, und ein erneuter Versuch darf ihn nicht überschreiben. Sende den gespeicherten Grund erneut mit oder lass ihn weg.
* **Stornieren, wenn es kein Zurück mehr gibt** – eine bestätigte Blutabnahme, eine abgeholte Sendung, ein versendetes oder aktiviertes Kit.

Drei Endpunkte sind bewusst nicht wiederholungssicher:

* [Blutabnahme bestätigen](https://docs.anivahealth.com/de/api/appointments/confirm-blood-draw.md) – ein zweiter Aufruf liefert `409`.
* [Ergebnisse per E-Mail senden](https://docs.anivahealth.com/de/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) und [Ergebnisse per E-Mail senden](https://docs.anivahealth.com/de/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) – jeder Aufruf verschickt eine E-Mail. Ein erneuter Versuch nach einem Timeout oder `5xx` kann dem Kunden eine doppelte E-Mail schicken.

## Schreibvorgänge, die etwas erstellen

Fünf Endpunkte akzeptieren einen optionalen `Idempotency-Key`-Header mit maximal 255 Zeichen:

* [Profil erstellen](https://docs.anivahealth.com/de/api/profiles/create-profile.md)
* [Termin erstellen](https://docs.anivahealth.com/de/api/appointments/create-appointment.md)
* [Heimtest-Kit-Bestellung erstellen](https://docs.anivahealth.com/de/api/home-kit-orders/create-home-kit.md)
* [Sendung erstellen](https://docs.anivahealth.com/de/api/shipments/create-shipment.md)
* [Dokument hochladen](https://docs.anivahealth.com/de/api/documents/upload-document.md)

Ein Schlüssel, vier Versuche, eine Bestellung – was du zurückbekommst, hängt davon ab, wann du es erneut versuchst und ob der Body übereinstimmt:

![Sequenzdiagramm: Ein Duplikat, das 350 ms nach der ersten Anfrage gesendet wird, erhält 409, solange diese Anfrage noch läuft, die erste liefert 201, ein späterer erneuter Versuch mit demselben Schlüssel liefert dieselbe Bestellung mit der Kennzeichnung Idempotent-Replayed, und derselbe Schlüssel mit geändertem Body liefert 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Schlüssel gelten jeweils für deinen API-Schlüssel **und** den Endpunkt, sodass sie weder mit denen anderer Partner noch mit demselben Schlüssel an anderer Stelle kollidieren.

* **Gleicher Schlüssel, gleicher Body** → 24 Stunden lang bekommst du die ursprüngliche Antwort zurück, markiert mit `Idempotent-Replayed: true`. Feldreihenfolge und Leerzeichen spielen keine Rolle.
* **Gleicher Schlüssel, anderer Body** → `409`.
* **Ein leerer `Idempotency-Key`** → `400`, statt ignoriert zu werden.

### Wann der Schlüssel freigegeben wird

Die Erstellung ist **nicht atomar** – ein `5xx` bedeutet nicht, dass nichts geschrieben wurde.

* **Die Anfrage ist fehlgeschlagen, bevor etwas erstellt wurde** → der Schlüssel wird freigegeben, sodass du es damit erneut versuchen kannst.
* **Die Anfrage ist fehlgeschlagen, nachdem etwas erstellt wurde**, oder **hat gar keine Antwort geliefert** → der Schlüssel bleibt belegt und erneute Versuche erhalten `409`. Ruf die Ressource ab, um zu prüfen, ob sie existiert, und verwende einen neuen Schlüssel, falls nicht.

> [!NOTE]
>
> Eine Wiederholung liefert den Antwort-Body zurück, der beim Erstellen der Ressource gespeichert
> wurde – einen Snapshot, keinen aktuellen Stand. Wenn sich die Ressource inzwischen geändert hat,
> ruf sie direkt ab.

### Einige Erstellungen haben auch einen natürlichen Schlüssel

Zwei Endpunkte lehnen Duplikate von sich aus ab, unabhängig von jedem Header:

* [Termin erstellen](https://docs.anivahealth.com/de/api/appointments/create-appointment.md) erlaubt einen Termin pro Profil, Standort und Zeitpunkt. Eine Wiederholung liefert `409` mit der bestehenden `appointment_id`.
* [Profil erstellen](https://docs.anivahealth.com/de/api/profiles/create-profile.md) liefert `409`, wenn für `email` bereits ein Profil existiert. Lässt du `email` weg, wird pro Anfrage ein eindeutiger Platzhalter erzeugt, sodass Wiederholungen *tatsächlich* getrennte Profile erstellen.

Wenn beides zutrifft, erhältst du das `409` des natürlichen Schlüssels, und nur dieses enthält das Zusatzfeld (`appointment_id` oder einen `error_name`-Diskriminator) – ein Idempotenz-`409` enthält nur `error`, lies diese Felder also defensiv aus.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.