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.