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

# Idempotence et reprise

## Idempotency-Key

Une écriture peut réussir alors que sa réponse se perd en route. Envoyez une `Idempotency-Key` pour pouvoir la renvoyer sans risque de doublon.

* **Obligatoire** sur les écritures d’une location : création, modification, suppression, actions (annulation, départ, retour, report, changements, options) et paiements. Absente, la requête répond `400`. Facultative sur toutes les autres écritures, photos comprises.
* Sur une opération qui accepte `?dryRun=true`, l’aperçu n’exige pas de clé : il n’écrit rien.
* Valeur : 1 à 255 caractères imprimables, unique par opération (un UUID, par exemple), réutilisée à l’identique pour chaque renvoi de cette opération. Portée : votre clé API, la méthode et le chemin. Durée : 24 h.
* **Même clé, même corps** : la réponse d’origine est renvoyée à l’identique, avec l’en-tête `Idempotent-Replayed: true`.
* **Même clé, corps différent** : `422 IDEMPOTENCY_KEY_REUSED`.
* **Même clé, requête encore en cours** : `409 IDEMPOTENCY_IN_FLIGHT` avec `Retry-After` ; renvoyez après le délai.
* Seul un succès (`2xx`) est mémorisé. Après un refus survenu avant toute écriture, la même clé exécute de nouveau l’opération.
* **Écriture faite, réponse perdue** : sur les opérations qui déclarent `IDEMPOTENCY_ALREADY_APPLIED` (création de devis et de location, actions sur une location, paiements, enregistrement d’un entretien, suppression d’une photo), une écriture enregistrée dont la réponse a échoué (`5xx`) garde sa clé. Un renvoi répond `409 IDEMPOTENCY_ALREADY_APPLIED` avec `resourceId`, et l’en-tête `Location` quand la ressource se relit par un `GET`. Ne renvoyez pas : relisez la ressource. Sur les autres écritures, relisez la ressource avant de renvoyer après un `5xx`.

**Photos.** La préparation d’un dépôt ([`POST /rentals/{rentalId}/photo-uploads`](https://docs.lexio.rent/api-reference/depart-et-retour/create-rental-photo-uploads)) et l’enregistrement des photos déposées ([`POST /rentals/{rentalId}/photos`](https://docs.lexio.rent/api-reference/depart-et-retour/register-rental-photos)) ne sont pas mémorisés par l’`Idempotency-Key` : un renvoi exécute de nouveau l’opération, et l’enregistrement se reconnaît par son `uploadId`.

## Que renvoyer

| Réponse | Que faire |
| - | - |
| Erreur réseau, délai dépassé, `500`, `503` | renvoyer à l’identique avec la même `Idempotency-Key`, après `Retry-After` s’il existe ; sur une écriture qui ne déclare pas `IDEMPOTENCY_ALREADY_APPLIED`, relire d’abord la ressource |
| `409 IDEMPOTENCY_IN_FLIGHT`, `409 RENTAL_BUSY`, `429` | attendre `Retry-After`, puis renvoyer à l’identique |
| `409 IDEMPOTENCY_ALREADY_APPLIED` | ne pas renvoyer : relire la ressource désignée |
| `409 RENTAL_CHANGED`, `409 PRICE_CHANGED` | relire la ressource, puis décider : ne pas renvoyer à l’aveugle |
| Autres `4xx` | corriger la requête ; la nouvelle tentative prend une nouvelle clé |

## Numéro de commande

`partnerReference` est votre numéro de commande : unique par code partenaire, ce n’est pas un mécanisme de renvoi. Un doublon répond `409 ALREADY_EXISTS` (`field`, `conflictingId`). N’y mettez jamais un identifiant de paiement : une réservation a sa propre identité, indépendante de son paiement.

## Aperçu avant écriture

`?dryRun=true` exécute l’action jusqu’au bout puis l’annule : la réponse est celle de l’appel réel, y compris `effects.priceChange` et `effects.overpayment`, et rien n’est enregistré. Les actions qui l’acceptent sont marquées dans la référence.

* Une action qui modifie le prix accepte `expectedTotalTTC`. Passez-y `effects.priceChange.newTotalTTC` de l’aperçu (ou `totalTTC` de la location si `priceChange` est nul) : si le total recalculé s’en écarte d’une unité mineure ou plus, l’action répond `409 PRICE_CHANGED` sans rien écrire. Sans `expectedTotalTTC`, elle s’applique au prix du moment.
* Une modification qui ferait passer le total sous le montant déjà encaissé exige `overpaymentResolution` (`REFUND_PENDING` ou `NO_REFUND`, scope `payments.refund`) ; sinon `409 OVERPAYMENT_RESOLUTION_REQUIRED`. Une clé partenaire reçoit `resolvableByKey: false` : le loueur traite la baisse dans Lexio.


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