Guida

Idempotenza

Le richieste che modificano dati diventano sicure da ripetere se mandi un'Idempotency-Key. Se una richiesta si perde per un timeout, ripeterla con la stessa chiave restituisce il risultato originale invece di creare un duplicato.

L'header Idempotency-Key

Manda una chiave univoca (un UUID è l'ideale) su ogni POST, PUT o PATCH. Il server conserva il risultato legato a quella chiave per 24 ore e lo restituisce a ogni nuovo tentativo con la stessa chiave.

Le regole

Genera una chiave nuova per ogni operazione logica, prima del primo tentativo.
Riusa la stessa chiave per ripetere quella stessa operazione.
Riusare una chiave con un corpo diverso restituisce IDEMPOTENCY_KEY_REUSED, mai una corruzione silenziosa.
Le richieste GET ignorano l'header. Lo accettano anche quasi tutte le rotte DELETE, così ripetere una cancellazione resta sicuro.

Esempio

Creare un movimento con una chiave: ripetendo la chiamata ottieni lo stesso movimento, non un secondo.

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"}'