Guide

Idempotence

Une requête qui modifie des données peut être réessayée sans risque si vous envoyez un Idempotency-Key. Si une requête est perdue à cause d'un timeout, la rejouer avec la même clé renvoie le résultat d'origine au lieu de créer un doublon.

L'en-tête Idempotency-Key

Envoyez une clé unique (un UUID est idéal) à chaque POST, PUT ou PATCH. Le serveur stocke le résultat indexé par cette clé pendant 24 heures et rejoue ce résultat à chaque nouvelle tentative portant la même clé.

Les règles

Générez une nouvelle clé par opération logique, avant la première tentative.
Réutilisez la même clé pour les nouvelles tentatives de cette opération précise.
Réutiliser une clé avec un corps différent renvoie IDEMPOTENCY_KEY_REUSED, jamais de corruption silencieuse.
Les requêtes GET ignorent l'en-tête. La plupart des DELETE l'acceptent aussi, donc réessayer une suppression reste sûr.

Exemple

Création d'une transaction avec une clé : rejouer l'appel renvoie la même transaction, et non une seconde.

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: 7c2f9b1e-4a8d-4e3a-9c1b-2f6e8d0a1b3c" \     -X POST https://api.vokse.ai/households/current/transactions \     -d '{"accountId":"01J8ME9AZ2K3W7X4V5T6R7Q8S9","date":"2026-06-22","amountCents":-4250,"currency":"EUR","payeeName":"Mercadona"}'