Passer au contenu principal
L’API Hyperline prend en charge l’idempotence, vous permettant de réessayer des requêtes en toute sécurité sans effectuer accidentellement la même opération deux fois. Ceci est particulièrement utile lorsqu’une erreur réseau ou un délai d’expiration vous empêche de savoir si une requête a réussi.

​
Comment ça fonctionne

Transmettez un en-tête Idempotency-Key unique avec toute requête modifiant des données (POST, PUT, PATCH). Si la requête réussit, Hyperline met la réponse en cache pendant 24 heures. Toute requête ultérieure avec la même clé renvoie la réponse mise en cache au lieu de réexécuter l’opération. 
POST /v1/invoices
Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e

​
Générer des clés d’idempotence

Utilisez un UUID V4 ou toute chaîne suffisamment aléatoire (au moins 16 caractères). La clé doit être unique par intention d’opération — générez une nouvelle clé pour chaque opération distincte. 
const { randomUUID } = require("crypto");

const response = await fetch("https://api.hyperline.co/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ customer_id: "cus_123", ... }),
});

​
Comportement

ScénarioRésultat
Première requête avec une cléExécute normalement, met en cache la réponse
Nouvelle tentative avec la même clé et le même corpsRenvoie la réponse en cache (pas de ré-exécution)
Requête avec la même clé mais un corps ou une URL différentsRenvoie 417 Expectation Failed
Requêtes concurrentes avec la même cléRenvoie 409 Conflict pour la deuxième requête

​
Réponses d’erreur

409 Conflict — Requête en cours Une requête avec la même clé d’idempotence est en cours de traitement. Attendez que la requête d’origine se termine avant de réessayer. 417 Expectation Failed — Incohérence d’intention Une requête terminée existe pour cette clé, mais la nouvelle requête a une méthode, une URL ou un corps différent. Cela signifie généralement que vous avez réutilisé par erreur une clé pour une opération différente. Générez une nouvelle clé pour la nouvelle requête.

​
Bonnes pratiques

  • Générez les clés côté client avant l’envoi de la requête, afin que les nouvelles tentatives réutilisent la même clé.
  • Une clé par opération — ne réutilisez pas une clé pour des requêtes logiquement différentes.
  • Réessayez en cas d’erreurs réseau — si une requête expire, réessayez avec la même clé. L’opération ne sera pas dupliquée.
  • Ne réessayez pas en cas d’erreurs 4xx (sauf 409/429) — celles-ci indiquent un problème avec votre requête que la nouvelle tentative ne corrigera pas.

​
Endpoints pris en charge

Les clés d’idempotence sont acceptées sur tous les endpoints modifiant des données (POST, PUT, PATCH). Elles sont ignorées sur les requêtes GET puisque celles-ci sont déjà sûres à réessayer.