Toutes les requêtes POST, PATCH et DELETE nécessitent un en-tête Idempotency-Key. PUT accepte aussi cet en-tête : avec une clé, la requête suit les règles de cette page ; sans clé, elle s'exécute à chaque envoi.

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

Le rejeu a lieu sur la plateforme elle-même : https://api.dzbuild.app/v1 et l'alias dzbuild.com/api/v1 se comportent donc de la même façon. Une réponse stockée est conservée 24 heures et les rejeux reviennent avec Idempotency-Replay: 1.

Un POST /v1/orders réessayé avec la même clé et le même corps obtient la première réponse au lieu de créer une deuxième commande, quel que soit l'hôte appelé.

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.

POST /v1/keys et POST /v1/webhooks renvoient un secret affiché une seule fois, leur réponse n'est donc jamais stockée non plus. Un réessai avec la même clé exécute de nouveau l'appel et peut créer une deuxième clé ou un deuxième webhook. Consultez GET /v1/keys ou GET /v1/webhooks avant de réessayer l'un des deux.

⚠️ Attention — L'idempotence protège des réessais, pas des accès concurrents

La réponse n'est stockée qu'une fois la première requête terminé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.

Une clé appartient à la première requête qui l'a utilisée : sa méthode, son chemin et son corps. La query string n'entre pas dans la comparaison. Réutiliser une clé avec un corps, un chemin ou une méthode différents renvoie 422 avec le code idempotency_key_reuse et n'exécute rien. Le corps est comparé octet par octet : un réessai doit renvoyer exactement les octets de la première tentative, et non une copie reconstruite avec un autre ordre des champs ou d'autres espaces. Générez une clé par opération logique (un UUID neuf), jamais une par endpoint, par session ou par jour.

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, envoyez la requête corrigée avec une nouvelle Idempotency-Key : l'ancienne clé répond 422 idempotency_key_reuse pour le corps modifié. Les refus prononcés avant que la requête n'atteigne son traitement ne sont jamais stockés, par exemple un 401, les 403 liés au pilote, au plan ou à l'état de l'application, tout 429 et une Idempotency-Key absente ou mal formée. Un 403 pour un scope manquant vient du traitement lui-même : il est stocké comme tout autre 4xx. Les réponses 5xx ne sont pas mises en cache et peuvent être réessayées avec la même clé. Voir Erreurs.

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, un en-tête distinct, réservé aux GET, qui vaut toujours MISS.