> ## Documentation Index > Fetch the complete documentation index at: https://docs.metronome.com/llms.txt > Use this file to discover all available pages before exploring further. # Idempotence de l'API Cette page décrit comment Metronome prend en charge l'idempotence afin que vous puissiez réessayer les requêtes en toute sécurité sans créer de doublons. L'idempotence garantit que des opérations comme la création de clients ou l'ingestion d'événements d'utilisation aboutissent exactement une fois, même lorsque les requêtes sont retentées en raison de problèmes réseau, de délais d'expiration ou de la logique du client. Metronome fournit des mécanismes d'idempotence intégrés pour que vous puissiez réessayer les requêtes en toute sécurité sans introduire de données superflues. ## Comment Metronome prend en charge l'idempotence Metronome utilise différents mécanismes d'idempotence selon le type de données : | Méthode | Lieu d'utilisation | Portée | Comportement en cas de conflit | Rétention | | ----------------------------- | --------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------- | | **Transaction ID** | Ingestion d'événements (`/ingest`, Segment) | Événements d'utilisation | Ignore les événements ultérieurs avec le même ID | 34 jours | | **Ingest alias** | Écritures sur les clients (création ou mise à jour) | Clients | Renvoie `409 Conflict` si l'ingest alias est déjà utilisé | Jusqu'à libération | | **`uniqueness_key`** | Création de ressources | Ressources sélectionnées (voir ci-dessous) | Renvoie `409 Conflict` | Jusqu'à libération (disponible uniquement pour les Alerts) | | **En-tête `Idempotency-Key`** | Requêtes API POST | Cache de requêtes | Renvoie `409 Conflict` si les paramètres diffèrent | ≥ 24 heures | ## Ingestion d'événements Les [événements d'utilisation](/fr/guides/implement-metronome/core-concepts/send-usage-events) sont diffusés vers Metronome à grande échelle. Pour éviter les doublons, Metronome utilise le champ `transaction_id` comme clé d'idempotence. Une fois qu'un événement d'utilisation a été accepté avec un identifiant de transaction donné, Metronome ignore les événements ultérieurs portant le même identifiant de transaction au cours des 34 jours suivants. Cela vous permet de réessayer l'envoi d'événements en toute sécurité sans risque de duplication. ## Ingest aliases Les [ingest aliases](/fr/guides/implement-metronome/core-concepts/provision-customer#understand-ingest-aliases%E2%80%8B) mappent vos identifiants client internes à un ID client Metronome. Lorsque vous envoyez de l'utilisation indexée sur un ingest alias, Metronome l'associe automatiquement au bon client. Les ingest aliases sont également idempotents par nature, ce qui empêche la création d'entités client en double ou d'enregistrements conflictuels. **DÉPLACEMENT DES INGEST ALIASES** En raison de la nature idempotente des ingest aliases, vous ne pouvez déplacer un ingest alias entre clients que si vous le retirez d'abord du client d'origine. Cette règle s'applique aux clients archivés comme actifs. ## Requêtes API Metronome prend en charge deux méthodes pour garantir l'idempotence via l'API REST : * Utilisation de uniqueness keys (sur certains endpoints) * Utilisation de l'en-tête Idempotency-Key ### Uniqueness keys Metronome prend en charge l'idempotence pour les ressources couramment créées dans Metronome en acceptant un champ `uniqueness_key` dans la charge utile de la requête. Cette uniqueness key est stockée dans la ressource au sein de Metronome, et Metronome garantit qu'aucune ressource ne peut partager la même uniqueness key. Si vous tentez de créer une ressource avec une uniqueness key déjà utilisée, vous recevez une erreur HTTP `409 Conflict` avec le message *« This uniqueness key has already been used. »* Exemples de ressources avec uniqueness keys : * [Contract](/fr/api-reference/contracts/create-a-contract) * [Alert](/fr/api-reference/alerts/create-an-alert) * Commits et credits au niveau du client * Modifications de contrat \[bientôt disponible] ### En-tête Idempotency-Key Metronome recommande d'utiliser un en-tête `Idempotency-Key` pour les endpoints qui n'incluent pas de uniqueness key dédiée. Metronome prend en charge l'envoi d'un en-tête `Idempotency-Key` pour tous les endpoints POST. Si l'en-tête `Idempotency-Key` est fourni et que la requête commence à s'exécuter (elle passe la validation et n'entre pas en conflit avec une autre requête concurrente), les résultats de l'appel d'API sont persistés et les mêmes résultats sont renvoyés. **Comportement :** * Les clés doivent être uniques par requête * Une nouvelle tentative avec la même clé et des paramètres identiques renvoie le résultat d'origine. * Une nouvelle tentative avec la même clé mais des paramètres différents renvoie **HTTP `409 Conflict`**. * Metronome conserve les clés d'idempotence pendant au moins 24 heures. * L'idempotence s'applique même si une requête renvoie une erreur HTTP 500, ce qui signifie que Metronome met en cache et renvoie l'erreur **Comprendre l'idempotence avec les erreurs** : Lorsqu'une requête avec l'en-tête `Idempotency-Key` renvoie une erreur, Metronome met l'erreur en cache et la renvoie pour les nouvelles tentatives ultérieures utilisant la même clé d'idempotence. **Ce comportement suit les meilleures pratiques du secteur** — lorsqu'une opération échoue en cours d'exécution, les nouvelles tentatives sans examen manuel peuvent aggraver la situation. Dans ces cas, Metronome met en cache et renvoie l'erreur pour s'assurer que vous voyez l'échec de manière cohérente, étudiez l'état du système et décidez s'il faut réessayer ou résoudre manuellement. ## Bonnes pratiques * **Générez des clés déterministes pour l'idempotence basée sur les ressources** : dérivez les clés de la logique métier (par exemple, hash de l'ID externe et du type d'opération) afin que les nouvelles tentatives réutilisent toujours la même clé. * **Utilisez des clés aléatoires lorsque c'est approprié** : générez des UUID si vous n'avez pas besoin de clés déterministes (par exemple, en-tête `Idempotency-Key`). * **Adaptez les nouvelles tentatives à la durée de vie de la clé** : * Événements d'utilisation : réessayez dans les 34 jours. * Écritures API REST : réessayez dans les 24 heures. * **Préférez les uniqueness keys lorsqu'elles sont disponibles** : utilisez `uniqueness_key` pour la création de ressources comme les contrats plutôt que l'en-tête `Idempotency-Key`. * **Mettez en œuvre des nouvelles tentatives sûres** : réessayez toujours avec un backoff exponentiel et réutilisez la même clé.