Guía

Idempotencia

Las peticiones que modifican estado se pueden reintentar sin riesgo si envías una Idempotency-Key. Si una petición se pierde por un timeout, repetirla con la misma clave devuelve el resultado original en lugar de crear un duplicado.

La cabecera Idempotency-Key

Envía una clave única (un UUID es ideal) en cada POST, PUT o PATCH. El servidor almacena el resultado indexado por ella durante 24 horas y reproduce ese resultado en cualquier reintento con la misma clave.

Las reglas

Genera una clave nueva por cada operación lógica, antes del primer intento.
Reutiliza la misma clave para los reintentos de esa misma operación.
Reutilizar una clave con un cuerpo distinto devuelve IDEMPOTENCY_KEY_REUSED, nunca una corrupción silenciosa.
Las peticiones GET ignoran la cabecera. La mayoría de los DELETE también la aceptan, así que reintentar un borrado es seguro.

Ejemplo

Crear una transacción con una clave: repetir la llamada devuelve la misma transacción, no una segunda.

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