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

# Idempotence

> Réessaie toute écriture en toute sécurité, sans rien créer deux fois

## Écritures qui modifient une ressource existante

Aucun en-tête n'est requis. Là où une répétition renvoyait auparavant une erreur, elle renvoie désormais l'état actuel :

| Endpoint | Un appel répété renvoie |
| - | - |
| [Annuler un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/cancel-appointment.md) | `200` avec le rendez-vous annulé |
| [Annuler un envoi](https://docs.anivahealth.com/fr/api/shipments/cancel-shipment.md) | `200` avec l'envoi annulé |
| [Annuler une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/cancel-home-kit.md) | `200` avec la commande annulée |
| [Activer une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/activate-home-kit.md) | `200`, si l'heure de prélèvement est identique |
| Supprimer des panels ou des biomarqueurs | `200`, qu'ils soient encore rattachés ou non |

Une répétition n'écrit rien et sa réponse contient `Idempotent-Replayed: true` — c'est cet en-tête qui te permet de distinguer « je l'ai annulé » de « c'était déjà annulé ».

Trois exceptions renvoient `409` à la place :

* **Activer avec un `activated_at` *différent*.** L'heure de prélèvement figure sur le rapport de laboratoire, une nouvelle tentative ne doit donc pas l'écraser silencieusement.
* **Annuler un rendez-vous déjà annulé avec un `cancellation_reason` *différent*.** Même logique : le motif enregistré peut avoir été corrigé depuis, et une nouvelle tentative ne doit pas l'écraser. Renvoie le motif enregistré ou omets-le.
* **Annuler après le point de non-retour** — une prise de sang confirmée, un envoi collecté, un kit expédié ou activé.

Trois endpoints ne sont volontairement pas sûrs en cas de nouvelle tentative :

* [Confirmer une prise de sang](https://docs.anivahealth.com/fr/api/appointments/confirm-blood-draw.md) — un deuxième appel renvoie `409`.
* [Envoyer les résultats par e-mail](https://docs.anivahealth.com/fr/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) et [Envoyer les résultats par e-mail](https://docs.anivahealth.com/fr/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — chaque appel envoie un e-mail. Une nouvelle tentative après un timeout ou une erreur `5xx` peut envoyer un doublon au client.

## Écritures qui créent quelque chose

Cinq endpoints acceptent un en-tête `Idempotency-Key` optionnel de 255 caractères maximum :

* [Créer un profil](https://docs.anivahealth.com/fr/api/profiles/create-profile.md)
* [Créer un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/create-appointment.md)
* [Créer une commande de kit à domicile](https://docs.anivahealth.com/fr/api/home-kit-orders/create-home-kit.md)
* [Créer un envoi](https://docs.anivahealth.com/fr/api/shipments/create-shipment.md)
* [Téléverser un document](https://docs.anivahealth.com/fr/api/documents/upload-document.md)

Une clé, quatre tentatives, une commande — ce que tu obtiens dépend du moment où tu réessaies et de la correspondance du corps :

![Diagramme de séquence : un doublon envoyé 350 ms après la première requête reçoit 409 tant que celle-ci est encore en cours, la première renvoie 201, une nouvelle tentative ultérieure avec la même clé renvoie la même commande marquée Idempotent-Replayed, et la même clé avec un corps modifié renvoie 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Les clés sont limitées à ta clé API **et** à l'endpoint, elles n'entrent donc jamais en collision avec celles d'un autre partenaire ni avec la même clé utilisée ailleurs.

* **Même clé, même corps** → pendant 24 heures, tu reçois la réponse d'origine, marquée `Idempotent-Replayed: true`. L'ordre des champs et les espaces n'ont pas d'importance.
* **Même clé, corps différent** → `409`.
* **Un `Idempotency-Key` vide** → `400`, plutôt que d'être ignoré.

### Quand la clé est libérée

La création n'est **pas atomique** — une erreur `5xx` ne signifie pas que rien n'a été écrit.

* **La requête a échoué avant toute création** → la clé est libérée, tu peux donc réessayer avec la même clé.
* **La requête a échoué après une création**, ou **n'a jamais renvoyé de réponse** → la clé reste réservée et les nouvelles tentatives reçoivent `409`. Récupère la ressource pour vérifier si elle existe, puis utilise une nouvelle clé si ce n'est pas le cas.

> [!NOTE]
>
> Un appel rejoué renvoie le corps de réponse enregistré lors de la création de la ressource — un
> instantané, pas une lecture en direct. Si la ressource a changé depuis, récupère-la directement.

### Certaines créations ont aussi une clé naturelle

Deux endpoints rejettent les doublons d'eux-mêmes, indépendamment de tout en-tête :

* [Créer un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/create-appointment.md) autorise un seul rendez-vous par profil, lieu et horaire. Une répétition renvoie `409` avec l'`appointment_id` existant.
* [Créer un profil](https://docs.anivahealth.com/fr/api/profiles/create-profile.md) renvoie `409` lorsque `email` a déjà un profil. Omets `email` et une valeur de remplacement unique est générée par requête ; les répétitions créent donc *bien* des profils distincts.

Lorsque les deux s'appliquent, c'est le `409` de la clé naturelle qui est renvoyé, et lui seul contient le champ supplémentaire (`appointment_id` ou un discriminateur `error_name`) — un `409` d'idempotence ne contient que `error`, lis donc ces champs de manière défensive.


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