---
title: "Qu’est-ce qu’une clé d’idempotence ? Retries d’API sûrs"
description: "Une clé d’idempotence est un identifiant unique créé par le client pour qu’un retry ne répète pas son effet, comme un second débit. Fonctionnement et en-tête IETF."
url: https://broadrouter.com/fr/glossary/idempotency-key/
lang: fr
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduit de l’anglais avec l’aide de l’IA. [Lire l’original en anglais](https://broadrouter.com/glossary/idempotency-key/) (mis à jour le 2026-11-14).

# Clé d’idempotence (idempotency key)

Mis à jour 2026-11-14

Une clé d’idempotence est une valeur unique, généralement un identifiant aléatoire comme un UUID, qu’un client joint à une requête qui modifie un état, comme un paiement ou un achat. Si la même requête est renvoyée avec la même clé, le serveur renvoie le résultat d’origine au lieu d’exécuter l’action deux fois.

Aussi appelé : clé d’idempotence, requête idempotente, retry idempotent, en-tête Idempotency-Key, idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry

Le réseau lâche toujours au pire moment : après que le serveur a agi, mais avant que vous ayez reçu la réponse. Une clé d’idempotence rend le retry sûr.

## Comment ça marche

Le client crée une clé unique pour une action voulue et l’envoie avec la requête. Le serveur enregistre la clé avec le résultat. Si la même clé revient, le serveur rejoue le résultat enregistré au lieu d’agir de nouveau.

Le groupe de travail HTTPAPI de l’IETF normalise ce mécanisme sous la forme de l’en-tête de requête `Idempotency-Key` (draft 08, octobre 2026, pas encore une RFC). Il décrit la clé comme « a unique value generated by the client which the resource uses to recognize subsequent retries of the same request » (traduction : « une valeur unique générée par le client, qui permet à la ressource de reconnaître les nouvelles tentatives de la même requête ») et recommande un UUID ou un identifiant aléatoire équivalent. Les cas d’erreur du draft :

| Situation | Statut |
| --- | --- |
| Clé absente alors qu’elle est requise | 400 Bad Request |
| Requête d’origine encore en cours | 409 Conflict |
| Clé réutilisée avec un autre corps | 422 Unprocessable Content |

La Builders’ Library d’AWS fait le même constat côté client : « APIs with side effects aren’t safe to retry unless they provide idempotency. » (traduction : « on ne peut pas relancer sans risque une API à effets de bord, sauf si elle garantit l’idempotence. »)

## Pourquoi c’est important

Les retries avec [backoff exponentiel](https://broadrouter.com/fr/glossary/exponential-backoff/) sont une pratique courante, et beaucoup de SDK relancent automatiquement. Sans idempotence, un retry après un timeout peut créer deux commandes ou deux débits. Avec une clé, relancer est sûr, quoi qu’ait fait la première tentative. C’est donc un outil central pour les agents et les scripts qui achètent, réservent ou créent des choses sans supervision humaine.

## Sur BroadNet Inference

BroadNet applique ce principe à l’achat de [clés horaires](https://broadrouter.com/fr/blog/hourly-llm-api-key-explained/). `POST /portal/keys/hourly` accepte un `request_id` dans le corps JSON, et la documentation précise que « Idempotency is required for money safety » (traduction : « l’idempotence est indispensable pour sécuriser les paiements ») :

```bash
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
```

Réutiliser un `request_id` ne crée ni ne facture une autre clé. Après un timeout, une connexion coupée, un 409 `mint_in_progress` ou une 5xx, relancez avec le même `request_id`. Une relance renvoie `already_issued: true` et l’alias de la clé ; seule la première réponse réussie contient la clé en clair. La documentation précise : « Never generate a replacement id until the original result is known. » (traduction : « ne générez jamais d’identifiant de remplacement avant de connaître le résultat d’origine. »)

BroadNet ne documente pas de clé d’idempotence pour `/v1/chat/completions` ni pour les transcriptions. Voir [codes d’erreur et retries](https://broadrouter.com/fr/guides/errors-and-retries/) pour savoir quoi relancer dans ces cas, et [limites de débit](https://broadrouter.com/fr/glossary/rate-limit/) pour comprendre pourquoi des retries à l’aveugle peuvent aggraver une 429.

## Questions fréquentes

### Quand faut-il générer une nouvelle clé d’idempotence ?

Uniquement pour une nouvelle action voulue. Réutilisez la même clé pour chaque retry d’une même action, et n’en créez pas de nouvelle tant que vous ne connaissez pas l’issue de la première tentative.

### Les requêtes de chat completion à un LLM ont-elles besoin d’une clé d’idempotence ?

Générer du texte n’a pas d’effet de bord durable : une requête de chat répétée coûte en général simplement des tokens une seconde fois. La clé compte pour les appels qui débitent de l’argent ou créent des ressources. BroadNet ne la documente que pour l’achat de clés horaires, pas pour les chat completions.

### Que se passe-t-il si je réutilise une clé avec un autre corps de requête ?

Le draft de l’IETF indique que le serveur doit la rejeter avec 422 Unprocessable Content, car la clé est déjà liée à une autre requête.

## Voir aussi

-   [Backoff exponentiel (exponential backoff)](https://broadrouter.com/fr/glossary/exponential-backoff/) (terme)
-   [Limite de débit (rate limit)](https://broadrouter.com/fr/glossary/rate-limit/) (terme)
-   [Clé d’API (API key)](https://broadrouter.com/fr/glossary/api-key/) (terme)
-   [Concurrence (requêtes simultanées)](https://broadrouter.com/fr/glossary/concurrency/) (terme)
-   [Codes d’erreur de BroadNet Inference : quand réessayer ?](https://broadrouter.com/fr/guides/errors-and-retries/) (guide)
-   [Limiter vos clés API à vos serveurs avec une liste d’IP autorisées](https://broadrouter.com/fr/guides/api-keys-ip-allow-lists/) (guide)
-   [Agents de longue durée : timeouts, retries et checkpoints qui tiennent](https://broadrouter.com/fr/blog/long-running-agents-timeouts-retries/) (article)
-   [Clé d’API LLM horaire : un prix fixe à l’heure, expliqué](https://broadrouter.com/fr/blog/hourly-llm-api-key-explained/) (article)

Essayez-le sur votre vraie charge de travail. Les nouveaux comptes démarrent avec USD 5 de crédit pour Gemma et transcription. DeepSeek, GLM et Qwen3.8 nécessitent une recharge.

[Commencer](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=fr-glossary-idempotency-key&utm_content=page-cta) ·

**Sources**

-   [IETF HTTPAPI, The Idempotency-Key HTTP Header Field (Internet-Draft)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders’ Library, timeouts, retries et backoff avec jitter (jetons d’idempotence)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [Référence de l’API BroadNet Inference, clés horaires (idempotence par request\_id) (en anglais)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=fr-glossary-idempotency-key&utm_content=sources#hourly-keys)
