BroadRouter
Commencer

Clé d’idempotence (idempotency key)

Mis à jour

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 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. 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 ») :

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 pour savoir quoi relancer dans ces cas, et limites de débit 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.

Lire en MarkdownDemander à ChatGPTDemander à ClaudeDemander à Perplexity