Toutes les requêtes POST, PATCH et DELETE nécessitent un en-tête Idempotency-Key.
Idempotency-Key: order-create-2026-04-30-abc123
Format : 1 à 64 caractères, [A-Za-z0-9_-:.].
Utilisez une valeur stable et unique par opération logique (par exemple un UUID généré côté client).
Où le rejeu a réellement lieu
Le rejeu ne fonctionne que sur https://api.dzbuild.app/v1. La réponse est mise en cache 24 heures et les rejeux reviennent avec Idempotency-Replay: 1.
Sur l'alias interne dzbuild.com/api/v1, l'en-tête est validé mais aucun cache de rejeu n'est jamais alimenté — deux POST /v1/orders identiques portant la même clé créent deux commandes. Une raison de plus de n'intégrer que api.dzbuild.app.
Le cache est cloisonné par votre key_id et par l'Idempotency-Key : la même valeur envoyée sous une autre clé API ne déduplique pas.
POST /v1/signups et POST /v1/events exigent toujours l'en-tête, mais ils sont acceptés de façon asynchrone et leur réponse n'est jamais stockée — aucun cache de rejeu ne protège ces deux routes.
⚠️ Attention — L'idempotence protège des réessais, pas des accès concurrents
L'entrée de rejeu n'est enregistrée qu'après que votre réponse a déjà été renvoyée : deux requêtes dupliquées réellement simultanées peuvent donc s'exécuter toutes les deux. Sérialisez de votre côté les écritures sujettes aux doublons.
Les clés ne sont pas liées au corps de la requête
Nous comparons la clé seule — jamais les charges utiles. Réutiliser une clé avec un corps différent rejoue la première réponse au lieu de renvoyer une erreur, silencieusement, pendant 24 heures. Générez donc une clé par opération logique (un UUID neuf), jamais une par endpoint, par session ou par jour.
Les erreurs sont mises en cache elles aussi
Une réponse 4xx renvoyée pour une écriture est stockée et rejouée pendant 24 heures. Après avoir corrigé une erreur de validation, générez une nouvelle Idempotency-Key, sinon vous récupérerez simplement l'ancienne erreur. Les erreurs renvoyées avant le traitement de la requête — 401, 403, 429 ou une Idempotency-Key mal formée — ne sont jamais stockées. Les réponses 5xx ne le sont pas non plus et peuvent être réessayées avec la même clé. Voir Erreurs.
Distinguer un rejeu d'un appel neuf
Basez-vous sur Idempotency-Replay: 1 — un rejeu signifie qu'aucun nouvel effet de bord n'a eu lieu : sautez donc tout post-traitement local que vous exécuteriez après une véritable écriture.
À ne pas confondre avec X-Cache: HIT|MISS, un signal distinct, réservé aux GET, émis par le cache de lecture.